Authentication - Gradient

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

Authorization: Bearer grad_live_...

The same key works across both base URLs: 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 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.

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.

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 and turn, requires agents:invoke. Calling a custom tool requires tools:invoke. The hosted MCP server 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:

curl https://console.usegradient.dev/api/v1/whoami \
  -H "authorization: Bearer $GRADIENT_API_KEY"

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

​Where keys come from

​Scopes

​Checking a key

​Failures

Where keys come from

Scopes

Checking a key

Failures