API documentation

Keys and access management

API access is enabled per workspace by Stonewake, as part of your arrangement. Once enabled, workspace admins manage keys themselves. To arrange access for your workspace, contact your Stonewake representative or write to contact@stonewake.ai.

In the dashboard

A workspace admin can create, inspect, and revoke the workspace's keys from the dashboard. The full key is displayed once, at creation. What remains visible afterwards is each key's name, its display prefix (the first characters of the key, for matching a key you hold against the list), and its usage metadata.

Over the API

The same operations exist as endpoints under /org/api-keys. These are management endpoints: they authenticate with a workspace admin's session credential, the same identity the dashboard uses, not with an API key. API keys are read-only and cannot manage keys.

Create a key

POST /org/api-keys

{
  "name": "reporting-pipeline",
  "expires_at": "2027-01-01T00:00:00Z"
}

name is required, 1 to 120 characters. expires_at is optional; when present it must carry a timezone and lie in the future, otherwise the request is refused with 422. On success the response is 201:

{
  "secret": "swk_live_EXAMPLExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "key": {
    "id": "6e9c8a2f-6d1c-4a0b-9d5e-3f2a1b0c9d8e",
    "name": "reporting-pipeline",
    "key_prefix": "swk_live_EXA",
    "role": "viewer",
    "scopes": ["read"],
    "created_by": "admin@example.com",
    "created_at": "2026-08-13T09:30:00Z",
    "last_used_at": null,
    "expires_at": "2027-01-01T00:00:00Z",
    "revoked_at": null
  }
}

secret is the full key and appears only in this response. Store it immediately; it is not retrievable afterwards.

If API access is not enabled for the workspace, creation is refused with 403:

{
  "detail": "API access is not enabled for your workspace. Contact your Stonewake representative."
}

List keys

GET /org/api-keys responds 200 with the workspace's keys, newest first, and the workspace's API access status:

{
  "api_access_active": true,
  "api_access_expires_at": "2026-11-13T00:00:00Z",
  "keys": [
    {
      "id": "6e9c8a2f-6d1c-4a0b-9d5e-3f2a1b0c9d8e",
      "name": "reporting-pipeline",
      "key_prefix": "swk_live_EXA",
      "role": "viewer",
      "scopes": ["read"],
      "created_by": "admin@example.com",
      "created_at": "2026-08-13T09:30:00Z",
      "last_used_at": "2026-08-13T11:02:41Z",
      "expires_at": "2027-01-01T00:00:00Z",
      "revoked_at": null
    }
  ]
}

Revoked keys stay in the list: keys are never deleted, so the list is a complete history. api_access_expires_at is populated only while access is active and carries an end date; otherwise it is null. Listing works even when the workspace's API access has lapsed, so you can always see your keys.

Revoke a key

POST /org/api-keys/{key_id}/revoke responds 200 with the key's metadata, revoked_at now set.

• Revocation is immediate: the key is refused from its next request onwards.
• Revoking an already revoked key changes nothing; the original revoked_at is kept.
• An unknown key id responds 404 with { "detail": "API key not found." }. A key id belonging to another workspace answers the same 404; the API does not confirm the existence of anything outside your workspace.
• Revocation works regardless of the workspace's API access status. You can always kill a key.

Key object fields