> ## Documentation Index
> Fetch the complete documentation index at: https://evalgate.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API authentication

> Authenticate EvalGate API requests with Bearer tokens and organization-scoped SDK configuration.

# API authentication

Every EvalGate API request must include a bearer token. The token identifies the caller, determines which organization the request can access, and enforces the rate limits for your plan.

<Note>
  This bearer token is an **EvalGate API key**, not a model-provider key. Model-backed workflows use [bring your own provider key (BYOK)](/docs/platform/model-providers-byok); store that credential in Provider Keys or Model Gateway and never send it in the EvalGate `Authorization` header.
</Note>

## Add the authorization header

Include your API key in the `Authorization` header on every request:

```bash theme={null} theme={null}
curl https://evalgate.com/api/evaluations \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Requests without this header, or with an invalid key, receive `401 Unauthorized`.

## Get your API key

1. Open the [Developer Dashboard](https://evalgate.com/developer).
2. Go to **Settings -> API Keys**.
3. Create a new key.
4. Copy the API key and the Organization ID shown in the creation dialog.

<Warning>
  Treat your API key like a password. Do not commit it to version control. Store it in an environment variable or secret manager and pass it at runtime.
</Warning>

## Environment variables

The TypeScript and Python SDKs read these environment variables automatically:

| Variable                   | Description                                                                  |
| -------------------------- | ---------------------------------------------------------------------------- |
| `EVALGATE_API_KEY`         | Your API key, required for authenticated requests                            |
| `EVALGATE_ORGANIZATION_ID` | Your organization UUID, used by SDK methods that create org-scoped resources |

Set them in your shell or `.env` file:

```bash theme={null} theme={null}
export EVALGATE_API_KEY=sk_test_your_api_key_here
export EVALGATE_ORGANIZATION_ID=00000000-0000-4000-8000-000000000001
```

Direct REST API routes usually derive organization scope from the API key. Pass `organizationId` in the body or query only where an endpoint explicitly documents it.

## Authentication errors

<ResponseField name="401 Unauthorized" type="UNAUTHORIZED">
  Your request did not include an `Authorization` header, or the key is invalid, expired, or revoked.
</ResponseField>

<ResponseField name="403 Forbidden" type="FORBIDDEN / NO_ORG_MEMBERSHIP">
  Your key is valid but lacks the required permissions for this resource. This can mean the key does not have the necessary scopes, or the key does not belong to the organization that owns the requested resource.
</ResponseField>

Both errors follow the [standard error envelope](/docs/api/errors):

```json theme={null} theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Unauthorized",
    "details": null,
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

## Tool API authentication

`GET /api/mcp/tools` and `POST /api/mcp/call` are authenticated, organization-scoped HTTP Tool API endpoints. Tool discovery requires `eval:read`; only read-only tools can be executed. These endpoints are not a Model Context Protocol server.