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

# API key endpoints

> List, create, and revoke Gradient API keys as a signed-in admin. A key can't manage keys, so a leaked key can't extend its own access.

# API Keys

API keys provide programmatic access to the Gradient API. Keys are scoped to your organization and can be used for automation, CI/CD integration, and building custom tooling.

<Info>
  Keys are shown one time, stored only as a SHA-256 hash, scoped to one organization, and rate
  limited per key. See [Managing API keys](/docs/guides/managing-api-keys) for how to name and rotate a
  key, and [its security section](/docs/guides/managing-api-keys#security) for storage, scope, and
  limits.
</Info>

## List API Keys

```
GET /api/api-keys
```

Returns all API keys for your organization. The full key value is never returned after creation.

<Info>
  All endpoints on this page require a signed-in admin (owner or admin role). An API key cannot
  call them and gets `403`: A key that manages keys can extend its own access.
</Info>

<Accordion title="Response">
  ```json theme={null}
  {
    "apiKeys": [
      {
        "id": "uuid",
        "orgId": "uuid",
        "name": "Production Automation",
        "keyPrefix": "gai_abc12345",
        "scopes": [],
        "expiresAt": null,
        "lastUsedAt": "2025-01-15T10:00:00Z",
        "createdBy": "uuid",
        "createdAt": "2025-01-10T09:00:00Z",
        "isActive": true
      }
    ]
  }
  ```
</Accordion>

***

## Create API Key

```
POST /api/api-keys
```

<ParamField body="name" type="string" required>
  Human-readable label for the key
</ParamField>

<ParamField body="expiresAt" type="string">
  ISO 8601 expiry date
</ParamField>

<ParamField body="scopes" type="string[]">
  Reserved for future use
</ParamField>

<Warning>The `key` field is only returned once, at creation time. Store it securely - it cannot be retrieved again. Gradient keeps only a SHA-256 hash of it, so no endpoint and no screen can show it to you later.</Warning>

<Accordion title="Response - 201 Created">
  ```json theme={null}
  {
    "apiKey": {
      "id": "uuid",
      "orgId": "uuid",
      "name": "Production Automation",
      "keyPrefix": "gai_abc12345",
      "scopes": [],
      "expiresAt": null,
      "lastUsedAt": null,
      "createdBy": "uuid",
      "createdAt": "2025-01-10T09:00:00Z",
      "isActive": true
    },
    "key": "gai_abc123def456..."
  }
  ```
</Accordion>

***

## Revoke API Key

```
DELETE /api/api-keys/:id
```

Deactivates an API key immediately. Any requests using this key will be rejected.

<Accordion title="Response">
  ```json theme={null}
  {
    "ok": true
  }
  ```
</Accordion>


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