API Keys

Overview

API keys provide an alternative to JWT tokens for authenticating API requests. They are ideal for server-to-server integrations, automation scripts, and third-party applications.

Note

Key creation requires api_keys:write and the API keys component. Key reads and deletion require their corresponding permissions.

Authentication

Include your API key in the X-API-Key header:

curl -X GET "http://your-server:8080/api/contacts" \
  -H "X-API-Key: soosh_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

List API Keys

Get all API keys for your organization.

GET/api/api-keys

Response

{
  "status": "success",
  "data": [
    {
      "id": "uuid",
      "name": "Production Integration",
      "key_prefix": "a1b2c3d4e5f6g7h8",
      "last_used_at": "2024-01-15T10:30:00Z",
      "expires_at": "2025-12-31T23:59:59Z",
      "is_active": true,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Create API Key

Create a new API key.

POST/api/api-keys

Request Body

{
  "name": "Production Integration",
  "expires_at": "2025-12-31T23:59:59Z",
  "scopes": ["contacts:read", "chat:write"]
}

Field	Type	Required	Description
name	string	Yes	Friendly name for the API key
expires_at	string	No	RFC3339 expiration date (null for no expiration)
scopes	string[]	No	Immutable resource:action scopes; omitted scopes snapshot current available issuer grants; [] grants no access

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Production Integration",
    "key": "soosh_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "key_prefix": "a1b2c3d4",
    "expires_at": "2025-12-31T23:59:59Z",
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Caution

The full API key is only shown once when created. Store it securely - you won’t be able to retrieve it again.

Get API Key

Retrieve a single API key’s metadata. The full key is never returned.

GET/api/api-keys/{id}

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Production Integration",
    "key_prefix": "a1b2c3d4e5f6g7h8",
    "last_used_at": "2024-01-15T10:30:00Z",
    "expires_at": "2025-12-31T23:59:59Z",
    "is_active": true,
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Update API Key

Enable or disable an existing API key. Currently only the is_active flag can be changed.

PUT/api/api-keys/{id}

Request Body

{
  "is_active": false
}

Field	Type	Required	Description
is_active	boolean	No	Set false to disable the key without deleting it

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "name": "Production Integration",
    "key_prefix": "a1b2c3d4e5f6g7h8",
    "expires_at": "2025-12-31T23:59:59Z",
    "is_active": false,
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Delete API Key

Revoke an API key. This action is immediate and cannot be undone.

DELETE/api/api-keys/{id}

Response

{
  "status": "success",
  "data": {
    "message": "API key deleted successfully"
  }
}

Security Best Practices

1. Store keys securely - Use environment variables or secret management systems
2. Set expiration dates - Use expiring keys when possible for better security
3. Use descriptive names - Name keys by their purpose (e.g., “CI/CD Pipeline”, “CRM Integration”)
4. Rotate regularly - Delete and recreate keys periodically
5. Limit exposure - Never commit API keys to version control

Key Format

API keys follow the format: soosh_ followed by 32 hexadecimal characters.

Example: soosh_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

The key_prefix stored and returned by the API is the first 16 characters after the soosh_ prefix — enough to identify a key in the UI without exposing the secret.

Permissions

Every request requires the intersection of the key’s fixed scopes, the issuer’s current organization role, available components and record-level visibility. The issuer must remain active and a member of the key’s organization. A key cannot switch organizations or inherit its issuer’s platform super-administrator authority.

API keys support operational API routes; they cannot manage identity, users, roles, organizations, platform settings, other API keys, billing or audit access, or WebSockets.

GET /api/api-keys/scopes returns the eligible scope catalog with component availability and grantability. Scopes are included in key metadata responses. They cannot be expanded by updating a key: issue a replacement instead. Reactivating a disabled key requires both the acting administrator and original issuer to still hold all scopes.