Skip to main content

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

​
Create an API key

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

Open the Developer Dashboard

Sign in to your EvalGate account and navigate to the Developer Dashboard. Scroll down to the API Keys section.
2

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

Copy the key and organization ID

Your API key is displayed only once. Copy it before closing the dialog.
If you close the dialog without copying the key, you cannot retrieve it. Create a new key instead.
The dialog also shows your Organization ID. Save that UUID value alongside your key.

​
Use the API key in HTTP requests

Include your API key as a Bearer token in the Authorization header: 
Authorization: Bearer YOUR_API_KEY
The base URL for all API endpoints is https://evalgate.com. 
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.
.env
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. 
import { AIEvalClient } from '@evalgate/sdk';

const client = AIEvalClient.init();
If you need to pass credentials explicitly, pass them directly to the constructor: 
const client = new AIEvalClient({
  apiKey: process.env.EVALGATE_API_KEY,
  organizationId: process.env.EVALGATE_ORGANIZATION_ID,
});

​
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

Treat your API key like a password. Anyone who has it can make requests on behalf of your organization.
Never commit keys to version control. Add .env to your .gitignore file before creating it: 
echo ".env" >> .gitignore
Use CI secret stores for CI pipelines. In GitHub Actions, store credentials as repository secrets: 
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.

​
Rate limits

All API keys are subject to rate limits. If your integration receives 429 Too Many Requests, see the rate limits reference for per-plan limits and backoff guidance.