Skip to main content

​
API Keys

API keys provide authentication for the WebAPI external endpoints. Each key is tied to a firm and grants ADMIN-level access for that firm’s resources.

​
Create API Key

Generate a new API key for a firm. Only users with SUPERUSER or WORKFLOW_ENGINEER roles can create keys.
The full API key is returned only once at creation. Store it securely — it cannot be retrieved later.

​
Request

POST /external/api/v1/api-key
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

​
Body

​
firm_uuid
string
required
UUID of the firm to create the key for.

​
Response 201 Created

{
  "api_key": "abc1234$hashed_part_here",
  "key_prefix": "abc1234",
  "firm": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corp"
  }
}

​
How It Works

  1. Permission check — User must have SUPERUSER or WORKFLOW_ENGINEER role
  2. Firm lookup — The firm is found by firm_uuid
  3. Existing key check — Verifies the firm doesn’t already have an active key
  4. API user creation — If the firm doesn’t have an API user (web_api_only = true), one is created with ADMIN role
  5. Key generation — Prefix from the first 7 characters of the firm UUID + hashed portion, in format: {prefix}${hash}
  6. Storage — The key is hashed and saved; only the prefix is stored in plain text

​
Errors

CodeDescription
403 ForbiddenInsufficient permissions
404 Not FoundFirm not found
409 ConflictFirm already has an active key

​
List API Keys

Retrieve all active API keys (without the full key value).

​
Request

GET /external/api/v1/api-key?page=1&size=10
Authorization: Bearer <JWT_TOKEN>

​
Query Parameters

​
page
integer
default:"1"
Page number (starting from 1).
​
size
integer
default:"10"
Number of items per page.

​
Response 200 OK

{
  "count": 10,
  "items": [
    {
      "uuid": "key-uuid-here",
      "key_prefix": "abc1234",
      "is_active": true,
      "firm": {
        "uuid": "firm-uuid-here",
        "name": "Acme Corp"
      },
      "created_at": "2024-01-01T00:00:00Z",
      "last_used": "2024-01-15T14:30:00Z"
    }
  ]
}
The full api_key is never returned in list responses — only the key_prefix.

​
Errors

CodeDescription
403 ForbiddenInsufficient permissions (requires SUPERUSER)

​
Delete API Key

Soft-delete an API key. The key is marked as deleted and disabled.

​
Request

DELETE /external/api/v1/api-key/{api_key_uuid}
Authorization: Bearer <JWT_TOKEN>

​
Path Parameters

​
api_key_uuid
string
required
UUID of the API key to delete.

​
Response 204 No Content

Empty response body.

​
How It Works

  1. Permission check — User must have SUPERUSER role
  2. Key lookup — Find the key by UUID
  3. Soft delete — Sets deleted_at to current time and enabled to false

​
Errors

CodeDescription
403 ForbiddenInsufficient permissions
404 Not FoundKey not found