> ## 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.

# Authentication

> Create an API key, set environment variables, and initialize the EvalGate SDK.

# Authenticate with the EvalGate API

Every platform request requires an API key. SDK clients also need an organization ID when they create org-scoped resources such as traces and evaluations.

## EvalGate keys and provider keys are different

| Credential                  | What it authorizes                                                          | Where to configure it                                        |
| --------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------ |
| **EvalGate API key**        | SDK, CLI, and REST access to EvalGate                                       | Developer Dashboard and `EVALGATE_API_KEY`                   |
| **Provider or gateway key** | Model inference for LLM judges, synthesis, and other model-backed workflows | **Settings → Provider Keys** or **Settings → Model Gateway** |

EvalGate uses a **bring your own provider key (BYOK)** model and does not bundle
model inference credits. Your provider bills model usage directly. A provider
key is never a substitute for the EvalGate bearer token, and you should not put
it in `EVALGATE_API_KEY`. See [Model providers and BYOK](/docs/platform/model-providers-byok).

## Create an API key

API keys are created from the Developer Dashboard. You need an EvalGate account before you begin.

<Steps>
  <Step title="Open the Developer Dashboard">
    Sign in to your EvalGate account and navigate to the [Developer Dashboard](https://evalgate.com/developer). Scroll down to the **API Keys** section.
  </Step>

  <Step title="Create the key">
    Click **Create API Key**. Enter a descriptive name such as `Development Key` or `CI Pipeline`, select the scopes you need, then click **Create Key**.
  </Step>

  <Step title="Copy the key and organization ID">
    Your API key is displayed only once. Copy it before closing the dialog.

    <Warning>
      If you close the dialog without copying the key, you cannot retrieve it. Create a new key instead.
    </Warning>

    The dialog also shows your **Organization ID**. Save that UUID value alongside your key.
  </Step>
</Steps>

## Use the API key in HTTP requests

Include your API key as a Bearer token in the `Authorization` header:

```http theme={null} theme={null}
Authorization: Bearer YOUR_API_KEY
```

The base URL for all API endpoints is `https://evalgate.com`.

```bash theme={null} theme={null}
curl https://evalgate.com/api/traces \
  -H "Authorization: Bearer sk_test_your_api_key_here" \
  -H "Content-Type: application/json"
```

## Configure environment variables

Store credentials as environment variables so neither the SDK nor your code needs to hardcode them.

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

Both variables are required for SDK workflows that create org-scoped platform resources. Direct REST API routes derive the organization from the API key unless an endpoint explicitly documents an `organizationId` field.

## SDK auto-loading

Both the TypeScript and Python SDKs read `EVALGATE_API_KEY` and `EVALGATE_ORGANIZATION_ID` automatically when you call `.init()` with no arguments.

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  import { AIEvalClient } from '@evalgate/sdk';

  const client = AIEvalClient.init();
  ```

  ```python Python theme={null} theme={null}
  from evalgate_sdk import AIEvalClient

  client = AIEvalClient.init()
  ```
</CodeGroup>

If you need to pass credentials explicitly, pass them directly to the constructor:

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  const client = new AIEvalClient({
    apiKey: process.env.EVALGATE_API_KEY,
    organizationId: process.env.EVALGATE_ORGANIZATION_ID,
  });
  ```

  ```python Python theme={null} theme={null}
  import os
  from evalgate_sdk import AIEvalClient

  client = AIEvalClient(
      api_key=os.environ["EVALGATE_API_KEY"],
      organization_id=os.environ["EVALGATE_ORGANIZATION_ID"],
  )
  ```
</CodeGroup>

## Authentication errors

If a request fails with `401 Unauthorized`, check that:

* The `Authorization` header is present and formatted as `Bearer YOUR_API_KEY`.
* The key was copied in full.
* The key has not been deleted from the Developer Dashboard.
* The key scopes include the operation you're attempting.

## Security best practices

<Note>
  Treat your API key like a password. Anyone who has it can make requests on behalf of your organization.
</Note>

**Never commit keys to version control.** Add `.env` to your `.gitignore` file before creating it:

```bash theme={null} theme={null}
echo ".env" >> .gitignore
```

**Use CI secret stores for CI pipelines.** In GitHub Actions, store credentials as repository secrets:

```yaml theme={null} theme={null}
env:
  EVALGATE_API_KEY: ${{ secrets.EVALGATE_API_KEY }}
  EVALGATE_ORGANIZATION_ID: ${{ secrets.EVALGATE_ORGANIZATION_ID }}
```

**Create separate keys per environment.** Use one key for local development, a separate key for staging, and another for production.

**Rotate keys when team members leave.** Revoke keys for former team members immediately from the Developer Dashboard and issue new keys to active users.

Provider credentials have a separate lifecycle. Store, rotate, and revoke them
from provider settings, and also revoke them at the upstream provider. EvalGate
stores organization provider credentials encrypted before use and does not
return the plaintext credential after creation.

## Rate limits

All API keys are subject to rate limits. If your integration receives `429 Too Many Requests`, see the [rate limits reference](/docs/platform/rate-limits) for per-plan limits and backoff guidance.