API Keys

List API keys

get

List all API keys for a workspace with pagination. Filter by role, or search a key's name or key ID. Requires ApiKey.view permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

sort_bystring[]OptionalDefault: []

limitinteger · max: 200OptionalDefault: 50

continuation_tokenanyOptional

mine_onlybooleanOptionalDefault: false

searchstring · min: 1 · max: 200 · nullableOptional

Case-insensitive match on the key's name or key ID.

rolestring · enum · nullableOptional

Only keys with this role.

Possible values:

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokenanyOptional

401

Missing or invalid API key.

403

Insufficient permissions.

422

Validation Error

application/json

503

Canonical API key role configuration unavailable.

get/v1/{workspace_id}/api-keys

GET /v1/{workspace_id}/api-keys HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "123e4567-e89b-12d3-a456-426614174000",
      "created_by_entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "created_by_credential_id": "123e4567-e89b-12d3-a456-426614174000",
      "key_id": "text",
      "name": "text",
      "role": "text",
      "permissions": [
        "text"
      ],
      "expires_at": "2026-01-01T00:00:00.000Z",
      "last_used_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Create an API key

post

Create a new API key for a workspace. The response includes the plaintext api_key — store it securely, it cannot be retrieved again.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

namestring · min: 1 · max: 256 · nullableOptional

duration_daysinteger · min: 1 · max: 90Required

rolestring · enumOptionalDefault: memberPossible values:

permissionsstring[] · max: 128Optional

Permission names. Max 128 entries; each entry up to 128 chars.

Responses

201

Successful Response

application/json

key_idstringRequired

api_keystringRequired

namestring · nullableRequired

rolestringRequired

permissionsstring[]Required

expires_atstring · date-timeRequired

created_by_entity_idstring · uuid · nullableRequired

created_by_credential_idstring · uuid · nullableRequired

401

Missing or invalid API key.

403

Insufficient permissions or requested role exceeds caller access.

422

Invalid request body or role.

503

Canonical API key role configuration unavailable.

post/v1/{workspace_id}/api-keys

POST /v1/{workspace_id}/api-keys HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 72

{
  "name": "text",
  "duration_days": 1,
  "role": "member",
  "permissions": [
    "text"
  ]
}

{
  "key_id": "text",
  "api_key": "text",
  "name": "text",
  "role": "text",
  "permissions": [
    "text"
  ],
  "expires_at": "2026-01-01T00:00:00.000Z",
  "created_by_entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_by_credential_id": "123e4567-e89b-12d3-a456-426614174000"
}

Get the API-key role/permission catalog

get

Return the authoritative role→permission model: each role's default permission set (what an API key of that role may carry) plus the full permission universe. Clients use this to build the create-key form instead of hard-coding the matrix. Requires ApiKey.view permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

The authoritative role→permission model for API-key creation.

Serves the server-side source of truth (DEFAULT_ROLE_DEFINITIONS) so clients (console, SDK) stop hand-copying the matrix and drifting out of sync — a drift previously shipped Data:Query as a viewer default and made the default create flow 422. Human-facing labels/descriptions for individual permissions stay client-side (pure presentation); this payload is authorization truth only.

401

Missing or invalid API key.

403

Insufficient permissions.

get/v1/{workspace_id}/api-keys/permission-catalog

GET /v1/{workspace_id}/api-keys/permission-catalog HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "roles": [
    {
      "name": "text",
      "priority": 1,
      "description": "text",
      "permission_names": [
        "text"
      ]
    }
  ],
  "permissions": [
    {
      "name": "text",
      "namespace": "text",
      "action": "text"
    }
  ]
}

Delete an API key

delete

Revoke an API key. Requires ApiKey.delete permission.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

key_idstringRequired

Responses

204

Successful Response

No content

401

Missing or invalid API key.

403

Insufficient permissions.

404

API key not found.

422

Validation Error

application/json

delete/v1/{workspace_id}/api-keys/{key_id}

DELETE /v1/{workspace_id}/api-keys/{key_id} HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Rotate an API key

post

Replace an API key secret in one step. The old secret stops working immediately, and the response includes the new plaintext api_key exactly once.

Authorizations

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

key_idstringRequired

Body

duration_daysinteger · min: 1 · max: 90Required

Responses

200

Successful Response

application/json

key_idstringRequired

api_keystringRequired

namestring · nullableRequired

rolestringRequired

permissionsstring[]Required

expires_atstring · date-timeRequired

created_by_entity_idstring · uuid · nullableRequired

created_by_credential_idstring · uuid · nullableRequired

401

Missing or invalid API key.

403

Insufficient permissions.

404

API key not found.

422

Validation Error

application/json

post/v1/{workspace_id}/api-keys/{key_id}/rotate

POST /v1/{workspace_id}/api-keys/{key_id}/rotate HTTP/1.1
Host: platform.api-us.concurrence.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "duration_days": 1
}

{
  "key_id": "text",
  "api_key": "text",
  "name": "text",
  "role": "text",
  "permissions": [
    "text"
  ],
  "expires_at": "2026-01-01T00:00:00.000Z",
  "created_by_entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_by_credential_id": "123e4567-e89b-12d3-a456-426614174000"
}