API Keys

Create and manage API keys for programmatic access. API keys are an alternative to JWT tokens, designed for CI/CD pipelines, scripts, and MCP integration.

Create API Key

POST /v1/api-keys

curl -X POST https://api.sota.io/v1/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Pipeline"}'

Response (201 Created):

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "CI/CD Pipeline",
    "key": "sota_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "key_prefix": "sota_a1b2c3d4",
    "created_at": "2026-02-25T10:00:00Z"
  }
}

Important: The full key is only returned once at creation time. Store it securely -- it cannot be retrieved later.

List API Keys

GET /v1/api-keys

curl https://api.sota.io/v1/api-keys \
  -H "Authorization: Bearer <jwt>"

Response:

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "CI/CD Pipeline",
      "key_prefix": "sota_a1b2c3d4",
      "last_used_at": "2026-02-25T14:30:00Z",
      "created_at": "2026-02-25T10:00:00Z"
    }
  ]
}

Note: The full key is not returned in list responses -- only the key_prefix for identification.

Delete API Key

DELETE /v1/api-keys/:id

curl -X DELETE https://api.sota.io/v1/api-keys/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <jwt>"

Returns 204 No Content.

Security

• API keys are stored as SHA-256 hashes -- the plain text key is never stored
• User keys are prefixed with sota_ for easy identification
• Partner API keys use the sotap_ prefix (see Partner API)
• Keys created via partner provisioning also use the sota_ prefix and behave identically to user-created keys
• Keys inherit the permissions of the user who created them
• Keys do not expire but can be revoked at any time

Usage

Use the API key as a Bearer token in the Authorization header:

curl https://api.sota.io/v1/projects \
  -H "Authorization: Bearer sota_a1b2c3d4e5f6..."