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

# Create and manage Gradient API keys

> Create, rotate, and revoke Gradient API keys, and see what a key can and can't reach when you automate invitations or pull scores.

# Managing API Keys

API keys let you interact with the Gradient API programmatically - useful for bulk invitations, CI/CD integrations, score retrieval, and building custom tooling.

## Creating an API key

1. Go to **Settings** in the admin portal
2. Navigate to the **API Keys** section
3. Click **Create API Key**
4. Give it a descriptive name (for example, "CI Automation" or "HR System Integration")
5. Copy the key immediately - it won't be shown again

<Info>
  Key management is for signed-in admins only. A key cannot create, list, or revoke keys, so a
  leaked key cannot extend its own access. The `/api/api-keys` endpoints return `403` to a key.
</Info>

<Warning>Store your API key securely. It provides full access to your organization's data. Never commit keys to version control or share them in plaintext.</Warning>

## Using your API key

Include the key in the `Authorization` header of every request:

```bash theme={null}
curl https://app.trygradient.ai/api/assessments \
  -H "Authorization: Bearer gai_abc123def456..."
```

The `gai_` prefix identifies Gradient API keys. Keys are scoped to your organization - they can access all resources within your org but nothing outside it.

## Key lifecycle

### Rotation

Create the new key, move your systems onto it, then revoke the old one. Both keys work at the same
time, so a rotation needs no outage.

### Expiry

For temporary or contractor access, set an expiration date in the create dialog. An expired key is
rejected the same way as a revoked one.

### Revoking a key

Open **Settings, API Keys**, find the key by its name or prefix, and click **Revoke**. Any requests
using the revoked key will be rejected immediately. The next request fails the lookup, so there is
no cache to wait for.

### Monitoring usage

The **API Keys** section shows the name, prefix, last-used time, and active state of each key. A
key with no recent use is a candidate for revocation.

## Best practices

* **Use descriptive names** - Name keys after their purpose ("ATS Integration", "Nightly Score Export") so you know what to revoke if needed
* **Rotate regularly** - Create new keys and revoke old ones periodically
* **One key per integration** - Don't share keys across different systems, so you can revoke access granularly
* **Set expiry dates** - For temporary or contractor access, always set an expiration

## Security

### How a key is stored

A key holds 32 bytes from a cryptographic random generator, with the `gai_` prefix. Gradient shows
the full key one time, in the response to the create request.

The database holds only a **SHA-256 hash** of the key, together with a short display prefix such as
`gai_abc12345`, the active state, and the optional expiry. To authenticate a request, Gradient
hashes the key you send and looks for that hash. A leak of the database therefore does not give
anyone a usable key.

All traffic uses HTTPS, and the key travels in the `Authorization` header. Gradient does not accept
a key in a query parameter, because a URL goes into logs and browser history.

<Warning>
  Because the key is shown one time, your own secrets store is the only copy. Put it there at
  creation.
</Warning>

### What a key can reach

**One organization.** Every request resolves to exactly one organization, and Gradient filters each
query by that organization.

**No workspace role.** A key is a machine caller, not a person, so it holds no
[workspace role](/docs/concepts/members-and-permissions). API keys can read assessments and change their settings fields. Keys can also invite
candidates, read transcripts and scores, export data, and release feedback. Keys cannot create an
assessment or edit its content. Only Gradient staff can do that.

These actions need a signed-in person, and a key gets `403`:

| Action | Why a person is required |
| - | - |
| Invite, re-role, or remove a member | It changes who has access. |
| Manage billing | It is a commercial act. |
| Change org settings, branding, or feature flags | It changes the workspace itself. |
| Delete a candidate or an assessment permanently | It destroys data and cannot be undone. |
| Reopen a finished session | It discards a candidate's work and replaces a score. |
| Record a calibration grade or a pairwise judgement | The record names the person who judged. |
| Create, list, or revoke API keys | A key that manages keys can extend its own access. |

A key cannot manage keys. If a key leaks, revoke it in the dashboard, and the incident ends there:
The leaked key cannot have made a replacement for itself.

### Rate limits

Each key gets **300 requests per minute** by default, counted in a fixed 60-second window. A
request over the limit gets `429` with these headers:

| Header | Meaning |
| - | - |
| `Retry-After` | Seconds until the window rolls over. |
| `X-RateLimit-Limit` | Requests permitted in a window. |
| `X-RateLimit-Remaining` | Requests left in this window. |

Gradient counts the request before it validates the key, so an unknown key uses the same budget as
a valid one. This throttles an attempt to guess key material.

### Evidence for an audit

Gradient records `api_key.created` and `api_key.revoked` in the organization audit log, with the
actor, the key prefix, and the expiry. It never records the key. An owner reads the log at
**Settings, Audit log**.

### Behind your own gateway

Many customers put their own API gateway in front of Gradient. Both patterns work:

* The gateway holds the key and forwards it unchanged. The key is then the credential between your
  gateway and Gradient, and your gateway authenticates your internal callers.
* The gateway ends the connection and makes a new request with the key. Nothing changes for
  Gradient: Whatever sends the key is the client.

In both patterns, the rate limit applies to the total traffic of the gateway. If you need requests
to come from a fixed set of addresses, tell us, and we can add an allowlist at the edge.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.