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

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

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.