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, the Authorization header bearer method, and the authorization-server origin. Follow that link to RFC 8414 metadata for EvalGate’s human-approved RFC 8628 device grant. The grant uses the server-owned public client evalgate-agent; it does not support dynamic registration or identity assertions. The shared client ID selects the flow; it does not authenticate or identify the requesting agent. The signed-in person’s code confirmation, tenant selection, and scope approval remain the security boundary.

​
Obtain a key

An authorized organization member can create a key from Developer → API Keys in the EvalGate dashboard. An RFC 8628 client can POST form-encoded client_id=evalgate-agent and its space-separated scope to /oauth/device/authorization, then poll /oauth/token with the returned device code. For JSON-only clients, use the equivalent handoff:
  1. POST /api/agent-setup/start with a descriptive client_name and the minimum requested_scopes.
  2. Show the returned verification_uri and user_code to a person.
  3. The person signs in with GitHub or Google and approves the displayed organization and scopes.
  4. Poll POST /api/agent-setup/poll no faster than the returned interval.
The approved API key is returned once and expires after 90 days. Store it in a secret manager or agent runtime secret and never put it in prompts, source control, logs, or tool results. The OAuth token endpoint returns that same opaque, revocable API-key record as the access token. Neither flow is anonymous identity issuance.

​
Safe test mode

After pickup, call public MCP server/discover, authenticated tools/list, and read-only project.plan. Those MCP operations make no model-provider call, persist no hosted evaluation result, and cannot enable paid overage. See the MCP request example. For local checks, evalgate gate --offline blocks EvalGate’s built-in and configured provider-backed checks unless network use is explicitly enabled. Custom in-process evaluators remain project code and can still use the network; hard network denial for wrapped project commands is available only when Linux unshare succeeds. This is not a production-like sandbox.

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