Skip to main content
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, 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.

Agents

The graphs your team builds and publishes.

Custom tools

Deployed code your agents call at runtime.

Datasets

Postgres databases that seed testing and evals.

Results

Traces and rubric scores across the organization.

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

​
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: See Authentication for the exact header format.

​
Create a key

1

Open the keys card

Go to Settings and find Organization API keys. Only an admin can create a key.
2

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

Copy the key

Copy the key the moment it is shown, then store it somewhere safe.
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.

​
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:
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.
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.

Authentication

How the Bearer header works across the API, CLI, and MCP.

Billing

How usage on the organization is metered and invoiced.