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.

This bearer token is an EvalGate API key, not a model-provider key. Model-backed workflows use bring your own provider key (BYOK); store that credential in Provider Keys or Model Gateway and never send it in the EvalGate Authorization header.

Add the authorization header

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

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

Open the Developer Dashboard.
Go to Settings -> API Keys.
Create a new key.
Copy the API key and the Organization ID shown in the creation dialog.

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.

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:

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

UNAUTHORIZED

Your request did not include an Authorization header, or the key is invalid, expired, or revoked.

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.

Both errors follow the standard error envelope:

{
  "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.

Overview

Endpoints

API authentication

API authentication

Add the authorization header

Get your API key

Environment variables

Authentication errors

Tool API authentication

​API authentication

​Add the authorization header

​Get your API key

​Environment variables

​Authentication errors

​Tool API authentication

API authentication

Add the authorization header

Get your API key

Environment variables

Authentication errors

Tool API authentication