Skip to main content

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

​
Using your API key

Include the key in the Authorization header of every request:
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.
Because the key is shown one time, your own secrets store is the only copy. Put it there at creation.

​
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. API keys support creating and editing assessments, inviting candidates, reading transcripts and scores, and releasing feedback. These actions need a signed-in person, and a key gets 403: 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: 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.