Skip to main content

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.

​
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 (e.g., “CI Automation”, “HR System Integration”)
  5. Copy the key immediately - it won’t be shown again
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: 
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

​
Expiry

You can set an expiration date when creating a key: 
curl -X POST https://app.trygradient.ai/api/api-keys \
  -H "Authorization: Bearer gai_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Temporary Access",
    "expiresAt": "2025-06-01T00:00:00Z"
  }'

​
Revoking a key

To immediately disable a key: 
curl -X DELETE "https://app.trygradient.ai/api/api-keys/KEY_ID" \
  -H "Authorization: Bearer gai_your_key"
Any requests using the revoked key will be rejected immediately.

​
Monitoring usage

List all keys and check their last usage: 
curl https://app.trygradient.ai/api/api-keys \
  -H "Authorization: Bearer gai_your_key" | jq '.apiKeys[] | {name, keyPrefix, lastUsedAt, isActive}'

​
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