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

> Create and manage API keys for programmatic 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.

## List API Keys

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

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

<Info>Requires admin role (owner or admin).</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.</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>