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.

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 for how to name and rotate a key, and its security section for storage, scope, and limits.

List API Keys

GET /api/api-keys

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

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.

Response

{
  "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
    }
  ]
}

Create API Key

POST /api/api-keys

string

required

Human-readable label for the key

string

ISO 8601 expiry date

string[]

Reserved for future use

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.

Response - 201 Created

{
  "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..."
}

Revoke API Key

DELETE /api/api-keys/:id

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

Response

{
  "ok": true
}

Overview

Endpoints

API Keys

API Keys

List API Keys

Create API Key

Revoke API Key

​API Keys

​List API Keys

​Create API Key

​Revoke API Key

API Keys

List API Keys

Create API Key

Revoke API Key