Issue an API key

Issues an ApiKey with a role, a scope (organization for keys that manage Workspaces, or workspace hard-bound to one Workspace), and a per-minute rate limit. Public Runner enrollment is BYOC-only. The owner shape is read-compatible and its principal claim ceiling is enforced. Owner-scoped Runner credentials are issued through server-stamped pairing; this generic API-key surface rejects a caller-asserted owner. Requires an Idempotency-Key, because secret issuance must always have an exact recovery identity. The plaintext secret is returned only in this response and is never readable again; only its keyed digest is stored as authentication authority. API keys are server-side credentials and must never be exposed to a browser or end user.

Checkfu support posture: alpha; hosted. Required evidence journey: tenant-control. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.

POST /v1/organizations/{organization_id}/api-keys

Issue an API key

cURL

curl --request POST \
  --url https://api.checkfu.com/v1/organizations/{organization_id}/api-keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "display_name": "<string>",
  "scope": {
    "type": "organization"
  },
  "rate_limit_per_minute": 1073741823
}
'

201

{
  "api_key": {
    "id": "<string>",
    "organization_id": "<string>",
    "display_name": "<string>",
    "role": "root",
    "scope": {
      "type": "organization"
    },
    "api_key_type": "organization_managed",
    "rate_limit_per_minute": 1073741823,
    "runner_enrollment": {
      "placement": "local",
      "providers": [
        {
          "id": "<string>",
          "provider_revision": "<string>",
          "materialization_revision": "<string>",
          "drivers": [
            "<string>"
          ],
          "launch_kinds": [
            "trusted"
          ],
          "tiers": [
            "container"
          ],
          "platforms": [
            {
              "os": "linux",
              "architecture": "amd64"
            }
          ],
          "network_modes": [
            "none"
          ],
          "retention_modes": [
            "durable"
          ],
          "package_materialization": true,
          "max_mounts": 1,
          "minimum_resources": {
            "cpu_millis": 1,
            "memory_mib": 1,
            "disk_mib": 1,
            "max_duration_seconds": 1
          },
          "maximum_resources": {
            "cpu_millis": 1,
            "memory_mib": 1,
            "disk_mib": 1,
            "max_duration_seconds": 1
          },
          "browser_observation": {
            "accessibility_tree": true,
            "screenshot": true
          },
          "harness_owned_models": [
            {
              "kind": "cursor_api_key",
              "harness_profile_id": "<string>",
              "harness_profile_revision_number": 1,
              "harness_release_digest": "<string>",
              "provider": "cursor",
              "model": "<string>"
            }
          ],
          "session_sandbox": true,
          "runtime_assurances": {
            "compute_accounting": true,
            "network_isolation": true,
            "bounded_start": true,
            "bounded_cancel": true,
            "teardown": true
          },
          "acp_transport": "stdio",
          "snapshot_clone": true,
          "snapshot_custody": "runner",
          "mount_kinds": [
            "uploaded_project"
          ]
        }
      ],
      "plane_protocols": [
        "model-gateway-v1"
      ],
      "runner_pool": "<string>",
      "owner": {
        "principal": "<string>",
        "machine_label": "<string>"
      }
    },
    "resource_version": 4503599627370495,
    "created_at": "<string>",
    "updated_at": "<string>",
    "revoked_at": "<string>"
  },
  "secret": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version · enum<string> · required

Available options: 2026-08-24

idempotency-key · string · required

Required string length: 1 - 255

Path Parameters

organization_id · string · required

Pattern: ^org_[0-9a-f]{32}$

Body

application/json

display_name · string · required

Required string length: 1 - 255

role · enum<string> · required

Available options: root, admin, developer, runner, viewer

scope · object · required

Option 1

Option 2

Show child attributes

rate_limit_per_minute · integer · required

Required range: 0 < x <= 2147483647

runner_enrollment · object

Show child attributes

Response

201

application/json

Success

api_key · object · required

Show child attributes

secret · string · required

Minimum string length: 1