> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usegradient.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate every Gradient API and MCP request with an organization-scoped API key sent as a Bearer token.

Every request to the engine and the console API authenticates with an organization API key, presented as a Bearer token:

```text theme={null}
Authorization: Bearer grad_live_...
```

The same key works across both [base URLs](/api/overview): the engine that runs agents and the console that serves tools, MCP, and management.

## Where keys come from

Create keys in the console under **API keys**. A key is scoped to one organization: it can only see and act on that organization's agents, tools, datasets, and phone numbers. To act on a different organization, create a key inside it. See [Organizations](/platform/organizations) for how organizations are structured.

Keys look like `grad_live_` followed by a random suffix. The full value is shown **once**, at creation. Copy it then, because the console only ever stores and displays a truncated preview afterward. If a key leaks, revoke it in the console; revoked keys stop verifying immediately.

<Warning>
  Treat a key like a password. Keep it in an environment variable such as `GRADIENT_API_KEY`, never in client-side code or a committed file.
</Warning>

## Scopes

Each key carries a set of scopes chosen when you create it. A request is checked against the scope its endpoint requires, so a narrowly scoped key can invoke agents without also being able to edit them. A key with `*` or `admin` passes every check.

| Family          | Scopes                                          | Grants                                                                      |
| --------------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
| Agents          | `agents:read`, `agents:write`, `agents:invoke`  | Read builder state, edit and publish graphs, send turns to published agents |
| Tools           | `tools:read`, `tools:write`, `tools:invoke`     | Inspect, deploy, and call custom tools                                      |
| Skills          | `skills:read`, `skills:write`                   | Read and manage organization skills                                         |
| Knowledge bases | `knowledge_bases:read`, `knowledge_bases:write` | Search and manage knowledge bases                                           |
| Providers       | `providers:read`, `providers:write`             | List connected LLM providers and manage BYOK keys                           |
| Phone numbers   | `phone_numbers:read`, `phone_numbers:write`     | List, buy, and release voice numbers                                        |
| Datasets        | `datasets:read`, `datasets:write`               | Read and manage datasets                                                    |
| Experiments     | `experiments:read`, `experiments:write`         | Read and manage red-team and rubric experiments                             |
| Traces          | `traces:read`, `traces:write`                   | Read and annotate trace runs                                                |

Running an agent, both [invoke](/api/agents/invoke) and [turn](/api/agents/turn), requires `agents:invoke`. Calling a custom [tool](/api/tools/invoke) requires `tools:invoke`. The [hosted MCP server](/api/mcp) authenticates the key first, then enforces the right scope on each individual tool it exposes.

## Checking a key

The console `whoami` route needs no scope and returns the organization the key resolves to, plus its scopes:

```bash theme={null}
curl https://console.usegradient.dev/api/v1/whoami \
  -H "authorization: Bearer $GRADIENT_API_KEY"
```

```json theme={null}
{
  "ok": true,
  "data": {
    "organization_id": "<organization-id>",
    "slug": "acme",
    "name": "Acme Health",
    "scopes": ["agents:invoke", "tools:invoke"]
  }
}
```

## Failures

| Status | Meaning                                                                                          |
| ------ | ------------------------------------------------------------------------------------------------ |
| `401`  | The `Authorization` header is missing or malformed, or the key is invalid or revoked             |
| `403`  | The key is valid but lacks the scope the endpoint requires; the response names the missing scope |
| `429`  | The key hit a usage limit; retry after the `Retry-After` header                                  |