Skip to main content
/
User Guide API Reference
Get Started

API Keys — API Reference

These endpoints let you manage API keys programmatically. Requires a key with the settings:write scope.

List API keys

GET /api/v1/settings/api-keys

Returns all API keys for the organisation (values are masked).

Response

{
  "data": [
    {
      "id": "key_abc123",
      "name": "Data warehouse export",
      "prefix": "alch_live_xxxx",
      "scopes": ["emissions:read", "reports:read"],
      "createdAt": "2024-01-15T08:00:00Z",
      "lastUsedAt": "2024-11-01T14:22:00Z",
      "expiresAt": null,
      "status": "active"
    }
  ]
}

Create an API key

POST /api/v1/settings/api-keys

Request body

{
  "name": "CI pipeline integration",
  "scopes": ["emissions:read", "emissions:write"],
  "expiresAt": "2025-12-31T23:59:59Z"
}
Field Type Required Description
name string ✅ Descriptive label
scopes string[] ✅ Permission scopes array
expiresAt ISO 8601 datetime Optional Omit for non-expiring key

Response (201)

{
  "data": {
    "id": "key_xyz789",
    "name": "CI pipeline integration",
    "value": "alch_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "scopes": ["emissions:read", "emissions:write"],
    "createdAt": "2024-11-01T09:00:00Z",
    "expiresAt": "2025-12-31T23:59:59Z",
    "status": "active"
  }
}

Important: The value field is returned only in this response. Store the key securely — it cannot be retrieved again.

Get an API key

GET /api/v1/settings/api-keys/{keyId}

Returns key metadata only (value is not included after creation).

Rotate an API key

POST /api/v1/settings/api-keys/{keyId}/rotate

Generates a new key value and immediately invalidates the old one.

Response (200)

{
  "data": {
    "id": "key_abc123",
    "value": "alch_live_new_xxxxxxxxxxxxxxxxxxxxxxxx",
    "rotatedAt": "2024-11-01T09:00:00Z"
  }
}

Update all systems using the old key before rotating in production. Rotation is immediate and irreversible.

Update an API key

PATCH /api/v1/settings/api-keys/{keyId}

Update name, scopes or expiry. Cannot change the key value (use rotate instead).

Request body

{
  "name": "Updated label",
  "scopes": ["emissions:read"],
  "expiresAt": "2026-12-31T23:59:59Z"
}

Revoke an API key

DELETE /api/v1/settings/api-keys/{keyId}

Permanently revokes the key. All future requests using this key will receive 401 INVALID_TOKEN. This action cannot be undone.

Response

204 No Content

Key object schema

Field Type Description
id string Unique key identifier
name string Descriptive label
prefix string First 12 chars of key (for display)
value string Full key value (creation response only)
scopes string[] Assigned permission scopes
createdAt datetime Creation timestamp
createdBy object { id, email } of creating user
lastUsedAt datetime or null Last authenticated request
expiresAt datetime or null Expiry timestamp or null
status string active, expired, revoked

Was this page helpful?