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

# Agent API-key authentication

> Discover and use EvalGate's organization-scoped bearer API keys from an agent.

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

```text theme={null}
GET https://www.evalgate.com/.well-known/oauth-protected-resource
```

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](https://evalgate.com/docs/platform/mcp-integration.md#public-bootstrap-request).

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:

| Scope | Access |
| - | - |
| `docs:read` | Read published EvalGate documentation and reference material. |
| `agent:read` | Inspect agent-facing status, capabilities, and attributable results. |
| `agent:execute` | Execute bounded, organization-scoped evaluation actions exposed to agents. |

`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:

```bash theme={null}
curl https://www.evalgate.com/api/evaluations \
  -H "Authorization: Bearer $EVALGATE_API_KEY"
```

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:

```text theme={null}
WWW-Authenticate: Bearer resource_metadata="https://www.evalgate.com/.well-known/oauth-protected-resource/api/evaluations"
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.