Skip to main content

API Keys API

The API Keys API allows you to manage API keys for your workspace. API keys are required for authenticating API requests.

Note: API keys are only available for Enterprise plan customers. Requires OWNER or ADMIN role.

List API Keys​

List all API keys for your tenant.

GET /api/api-keys

Response​

{
  "apiKeys": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenantId": "tenant-id",
      "name": "Production API Key",
      "prefix": "hbc_live_a1b2c3d4",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "lastUsedAt": "2024-01-15T12:00:00.000Z",
      "expiresAt": null,
      "revokedAt": null
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "tenantId": "tenant-id",
      "name": "Development API Key",
      "prefix": "hbc_live_e5f6g7h8",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "lastUsedAt": null,
      "expiresAt": "2025-01-01T00:00:00.000Z",
      "revokedAt": null
    }
  ]
}

Note: The full API key is only shown once when created. Only the prefix is returned in list responses.

Create API Key​

Create a new API key. The full key is only shown once in the response.

POST /api/api-keys

Request Body​

{
  "name": "Production API Key",
  "expiresAt": "2025-01-01T00:00:00.000Z",
  "scopes": ["read", "write"],
  "rateLimit": 2000,
  "allowedIps": ["192.168.1.1", "10.0.0.1"]
}

Required Fields​

  • name (string) - API key name (max 100 characters)

Optional Fields​

  • expiresAt (string, ISO 8601 date-time) - Expiration date. If not provided, key never expires
  • scopes (array of strings) - API key scopes. Valid values: "read", "write", "admin". If not provided, all scopes are granted
  • rateLimit (integer) - Custom rate limit per hour. If not provided, uses default (1000/hour)
  • allowedIps (array of strings) - IP whitelist. If provided, only requests from these IPs will be allowed

Response​

{
  "apiKey": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "tenantId": "tenant-id",
    "name": "Production API Key",
    "prefix": "hbc_live_a1b2c3d4",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "expiresAt": "2025-01-01T00:00:00.000Z",
    "scopes": ["read", "write"],
    "rateLimit": 2000,
    "allowedIps": ["192.168.1.1", "10.0.0.1"]
  },
  "key": "hbc_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
}

Important: Save the key value immediately. It will not be shown again.

Revoke API Key​

Revoke an API key. Revoked keys cannot be restored.

DELETE /api/api-keys/{id}

Path Parameters​

  • id (string, required) - API key ID

Response​

{
  "success": true
}

API Key Format​

API keys follow this format:

hbc_live_<32 hex characters>

Example: hbc_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

  • hbc_live_ - Prefix indicating a live API key
  • The remaining characters are randomly generated

Security Best Practices​

  1. Store keys securely - Use environment variables or secret managers
  2. Never commit keys - Never commit API keys to version control
  3. Use different keys - Use separate keys for different environments (production, staging, development)
  4. Set expiration dates - Set expiration dates for keys that don't need permanent access
  5. Use IP whitelisting - Restrict keys to specific IP addresses when possible
  6. Rotate keys regularly - Revoke and recreate keys periodically
  7. Monitor usage - Check lastUsedAt to identify unused keys
  8. Revoke unused keys - Immediately revoke keys that are no longer needed

Error Responses​

  • 400 - Bad Request (missing name, invalid expiration date, invalid scopes, name too long)
  • 401 - Unauthorized (invalid or missing API key)
  • 403 - Forbidden (requires Enterprise plan, requires OWNER/ADMIN role)
  • 404 - Not Found (API key doesn't exist)

Plan Requirement Error​

If you're not on the Enterprise plan, you'll receive a 403 error:

{
  "error": {
    "code": "UPGRADE_REQUIRED",
    "message": "API keys are only available for Enterprise plan customers."
  }
}