API Keys

The API Keys endpoints let you programmatically manage the keys used to authenticate with the Horizon API. All endpoints in this section require admin-level authentication via the Authorization: Bearer {admin_secret} header or the x-admin-secret header.

For an overview of how API keys work, see Authentication.

Create an API Key

POST /admin/api-keys

Create a new API key with the specified scopes and configuration.

Requires admin authentication via Authorization: Bearer {admin_secret} or x-admin-secret header.

Request Body

Parameter	Type	Description
client_name required	string	A human-readable name identifying the key's owner or purpose.
scopes required	string[]	Array of scope strings defining which skill categories this key can access.
rate_limit	number	Maximum requests per minute. Defaults to 100.
expires_at	string (ISO 8601)	Optional expiration timestamp. The key will be rejected after this time.

Request

curl -X POST https://api.horizonplatform.ai/admin/api-keys \
  -H "Authorization: Bearer your-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "backend-service",
    "scopes": ["quickbooks", "conversations"],
    "rate_limit": 200,
    "expires_at": "2027-01-01T00:00:00Z"
  }'

const response = await fetch('https://api.horizonplatform.ai/admin/api-keys', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-admin-secret',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    client_name: 'backend-service',
    scopes: ['quickbooks', 'conversations'],
    rate_limit: 200,
    expires_at: '2027-01-01T00:00:00Z',
  }),
});

const apiKey = await response.json();
console.log(apiKey.plaintext_key); // Save this — it is only shown once

import requests

response = requests.post(
    'https://api.horizonplatform.ai/admin/api-keys',
    headers={
        'Authorization': 'Bearer your-admin-secret',
        'Content-Type': 'application/json',
    },
    json={
        'client_name': 'backend-service',
        'scopes': ['quickbooks', 'conversations'],
        'rate_limit': 200,
        'expires_at': '2027-01-01T00:00:00Z',
    }
)

api_key = response.json()
print(api_key['plaintext_key'])  # Save this — it is only shown once

Response

// 201 Created
{
  "id": "key_a1b2c3d4",
  "client_name": "backend-service",
  "scopes": ["quickbooks", "conversations"],
  "rate_limit": 200,
  "enabled": true,
  "plaintext_key": "hz_live_k8x9m2n4p5q7r1s3t6u0v...",
  "created_at": "2026-03-18T14:30:00Z"
}

Response Fields

Parameter	Type	Description
id required	string	Unique identifier for the API key.
client_name required	string	The name provided at creation.
scopes required	string[]	The authorized scopes for this key.
rate_limit required	number	Maximum requests per minute.
enabled required	boolean	Whether the key is currently active.
plaintext_key required	string	The API key value. Only returned at creation time.
created_at required	string (ISO 8601)	When the key was created.

List API Keys

GET /admin/api-keys

Retrieve all API keys. The response never includes plaintext keys or hashes.

Requires admin authentication via Authorization: Bearer {admin_secret} or x-admin-secret header.

Request

curl -X GET https://api.horizonplatform.ai/admin/api-keys \
  -H "Authorization: Bearer your-admin-secret"

const response = await fetch('https://api.horizonplatform.ai/admin/api-keys', {
  headers: {
    'Authorization': 'Bearer your-admin-secret',
  },
});

const keys = await response.json();

import requests

response = requests.get(
    'https://api.horizonplatform.ai/admin/api-keys',
    headers={'Authorization': 'Bearer your-admin-secret'}
)

keys = response.json()

Response

// 200 OK
[
  {
    "id": "key_a1b2c3d4",
    "client_name": "backend-service",
    "scopes": ["quickbooks", "conversations"],
    "rate_limit": 200,
    "enabled": true,
    "created_at": "2026-03-18T14:30:00Z",
    "expires_at": "2027-01-01T00:00:00Z"
  },
  {
    "id": "key_e5f6g7h8",
    "client_name": "partner-integration",
    "scopes": ["sage-intacct"],
    "rate_limit": 100,
    "enabled": true,
    "created_at": "2026-03-10T09:15:00Z",
    "expires_at": null
  }
]

Revoke an API Key

DELETE /admin/api-keys/:id

Revoke an API key by setting its enabled status to false.

Requires admin authentication via Authorization: Bearer {admin_secret} or x-admin-secret header.

Revoking a key sets enabled to false. The key record is preserved for auditing purposes but will no longer authenticate any API requests.

Path Parameters

Parameter	Type	Description
id required	string	The unique identifier of the API key to revoke.

Request

curl -X DELETE https://api.horizonplatform.ai/admin/api-keys/key_a1b2c3d4 \
  -H "Authorization: Bearer your-admin-secret"

const response = await fetch(
  'https://api.horizonplatform.ai/admin/api-keys/key_a1b2c3d4',
  {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer your-admin-secret',
    },
  }
);

const result = await response.json();

import requests

response = requests.delete(
    'https://api.horizonplatform.ai/admin/api-keys/key_a1b2c3d4',
    headers={'Authorization': 'Bearer your-admin-secret'}
)

result = response.json()

Response

// 200 OK
{
  "message": "API key revoked successfully",
  "id": "key_a1b2c3d4"
}