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

# Organizations and API keys

> The organization is your tenant: manage members and roles, and create, scope, and revoke the API keys that authenticate the invoke endpoints, the CLI, and MCP.

In Gradient, the **organization** is the tenant. Your agents, custom tools, datasets, traces, phone numbers, members, API keys, and billing all belong to one organization. Everything you build is scoped to it, and every API key opens exactly one organization.

## The organization

One organization is one workspace you sign in to. When you join Gradient you either accept an invitation to an existing organization or create one during onboarding with a name and a URL slug.

Each organization gets its own isolated data plane, a dedicated Postgres project that backs its [datasets](/evaluate/datasets), so one organization's data is never visible to another. You manage an organization from **Settings** in the dashboard: rename it, set its voice policy, manage its webhook secret, and manage its API keys.

<CardGroup cols={2}>
  <Card title="Agents" icon="robot" href="/build/agents">
    The graphs your team builds and publishes.
  </Card>

  <Card title="Custom tools" icon="screwdriver-wrench" href="/build/custom-tools">
    Deployed code your agents call at runtime.
  </Card>

  <Card title="Datasets" icon="database" href="/evaluate/datasets">
    Postgres databases that seed testing and evals.
  </Card>

  <Card title="Results" icon="chart-line" href="/evaluate/results">
    Traces and rubric scores across the organization.
  </Card>
</CardGroup>

## Members and roles

Invite people, change their roles, and remove them from the organization profile in the dashboard. Every member has one of two roles:

* **Admin**: full access, and the only role that can create, re-scope, or revoke organization API keys.
* **Member**: builds and runs agents, but cannot manage API keys.

<Note>
  Invitations, role changes, and removals are handled in the organization profile UI, not through the API. A change there takes effect on the member's next load.
</Note>

## API keys

API keys are the **Bearer tokens** that authenticate programmatic access to your organization. Every key begins with `grad_live_`, belongs to exactly one organization, and carries a set of scopes that decide what it can do.

One key authenticates every programmatic surface:

* the published-agent [invoke endpoint](/api/agents/invoke) and the custom-tool [invoke endpoint](/api/tools/invoke),
* the `gradient` [CLI](/build/custom-tools) (`gradient login`, `deploy`, `invoke`, and the rest),
* the hosted [MCP server](/run/mcp).

See [Authentication](/api/authentication) for the exact header format.

### Create a key

<Steps>
  <Step title="Open the keys card">
    Go to **Settings** and find **Organization API keys**. Only an admin can create a key.
  </Step>

  <Step title="Name it and choose scopes">
    Select **New key**, give it a descriptive name, and pick its scopes. Leave the scopes unset to grant your organization's full set.
  </Step>

  <Step title="Copy the key">
    Copy the key the moment it is shown, then store it somewhere safe.
  </Step>
</Steps>

<Warning>
  The full key is shown **once**, right after you create it. Gradient keeps only a `grad_live_` prefix preview and can never show the full value again. If you lose it, revoke the key and create a new one.
</Warning>

### Scopes

A key's scopes are fine-grained, one per surface and action. For example:

* `agents:invoke`: send turns to your published agents.
* `agents:read` and `agents:write`: read builder state, or edit and publish agents.
* `tools:invoke`, `tools:read`, `tools:write`: call, inspect, or deploy custom tools.
* `traces:read`, `datasets:write`, `knowledge_bases:read`: and the equivalents for other surfaces.

A domain wildcard such as `agents:*` grants every action in that domain. A request made with a key that lacks the scope its endpoint requires is rejected with `403`, and the response names the missing scope. Admins can re-scope a key at any time from the same card.

### Verify a key

Call `whoami` to confirm which organization a key opens and what scopes it carries. It needs no scope of its own:

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

The response returns the `organization_id`, `slug`, `name`, and `scopes` for the presented key.

### Revoke a key

Revoke a key from the **Organization API keys** card. Revocation is immediate: the key stops working at once, and any request that presents it gets `401`. Revoking cannot be undone, so rotate by creating the replacement key first. Each key's **last used** time is shown to help you spot keys you can retire.

<Tip>
  Keys are rate-limited individually. A caller that exceeds the limit receives `429` with a `Retry-After` header: back off for that many seconds, then retry.
</Tip>

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    How the Bearer header works across the API, CLI, and MCP.
  </Card>

  <Card title="Billing" icon="credit-card" href="/platform/billing">
    How usage on the organization is metered and invoiced.
  </Card>
</CardGroup>