Skip to main content

​
Agent API-key authentication

EvalGate uses organization-scoped bearer API keys for programmatic access. An API key identifies the organization and key owner, is checked against the scopes granted to that key, and is attributed in usage and audit records. It is not a model-provider credential.

​
Discover the protected resource

Start with the RFC 9728-style metadata document:
The response describes the API resource, supported agent-facing scopes, and the Authorization header bearer method. EvalGate does not currently run a third-party OAuth authorization server for API keys, so this document does not advertise an authorization server, token endpoint, dynamic registration, or claim flow. Do not send an API key to an OAuth token endpoint.

​
Obtain a key

An authorized organization member creates a key from Developer → API Keys in the EvalGate dashboard. The full secret is shown once. Store it in a secret manager or an agent runtime secret and never put it in prompts, source control, logs, or tool results.

​
Least-privilege scopes

Grant only the scope required by the integration: agent:execute is for controlled product actions, not unrestricted repository mutation, credential management, billing changes, or arbitrary model execution. Existing EvalGate API keys and their established product scopes remain compatible; these three names are reserved for agent-facing integrations.

​
Use the credential

Send the key as a bearer token on every authenticated request:
The API derives organization scope from the key. Do not use a request body or query parameter to switch organizations.

​
Errors and discovery hints

An unauthenticated request returns 401 Unauthorized with a challenge like:
An authenticated key without a required scope returns 403 Forbidden with the standard EvalGate typed error envelope. Request the smallest missing scope from an authorized organization member; never substitute a provider key or a session cookie.

​
Key lifecycle

Rotate keys when an agent, repository, or operator changes ownership. Revoke a key immediately if it may have been exposed, and issue a replacement with the same minimum scopes. Key creation, use, and revocation remain attributable to the organization and are subject to the API’s rate limits.