> ## 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

> Create and manage API keys for programmatic access

# 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

<Tabs>
  <Tab title="Dashboard">
    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
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    curl -X POST https://app.trygradient.ai/api/api-keys \
      -H "Authorization: Bearer gai_existing_key" \
      -H "Content-Type: application/json" \
      -d '{"name": "CI Automation"}'
    ```

    The response includes the full key in the `key` field - this is the only time it's returned.
  </Tab>
</Tabs>

<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

### Expiry

You can set an expiration date when creating a key:

```bash theme={null}
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": "2027-01-01T00:00:00Z"
  }'
```

### Revoking a key

To immediately disable a key:

```bash theme={null}
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:

```bash theme={null}
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