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
- Go to Settings in the admin portal
- Navigate to the API Keys section
- Click Create API Key
- Give it a descriptive name (e.g., “CI Automation”, “HR System Integration”)
- Copy the key immediately - it won’t be shown again
The response includes the full key in the key field - this is the only time it’s returned. 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
Expiry
You can set an expiration date when creating a key:
Revoking a key
To immediately disable a key:
Any requests using the revoked key will be rejected immediately.
Monitoring usage
List all keys and check their last usage:
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
