Create workspace API key

Creates a workspace API key for the authenticated user and scopes it to the workspace via metadata. Effective access is the union of role permissions and explicit permissions. If neither is provided, role defaults to admin. This endpoint requires a signed-in session and does not accept API keys.

POST/api/v1/workspaces/{workspaceHandle}/api-keys

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*nonEmptyString

a non empty string

Length1 <= length

role?AssignableApiKeyRole

Hardcoded role available for new workspace API keys

Value in"admin" | "editor" | "viewer"

Example"admin"

permissions?

Explicit permissions attached directly to the API key. Effective access is the union of role permissions and these permissions.

Example

{
  "channels": [
    "read",
    "write"
  ],
  "messages": [
    "read",
    "write"
  ],
  "threads": [
    "read",
    "write"
  ]
}

expiresInMs?positive

a positive number

Range0 < value

Response Body

`application/json`

curl -X POST "https://loading/api/v1/workspaces/{workspaceHandle}/api-keys" \  -H "Content-Type: application/json" \  -d '{    "name": "Workspace integration key",    "role": "admin",    "permissions": {      "channels": [        "read",        "write"      ],      "messages": [        "read",        "write"      ],      "threads": [        "read",        "write"      ]    },    "expiresInMs": 2592000000  }'

{
  "key": "andi_live_3x7X7uPKnd2m4WQNkfC2fZb3TW4nYJd1",
  "apiKey": {
    "id": "key_6ZW0qF8cXTWETrdFM3A7yv",
    "name": "Workspace integration key",
    "start": "andi_l",
    "prefix": "andi_",
    "enabled": true,
    "role": "admin",
    "permissions": {
      "channels": [
        "read",
        "write"
      ],
      "messages": [
        "read",
        "write"
      ],
      "threads": [
        "read",
        "write"
      ]
    },
    "createdAt": "2026-03-05T19:00:00.000Z",
    "updatedAt": "2026-03-05T19:00:00.000Z",
    "expiresAt": null,
    "lastRequest": null
  }
}

{
  "issues": [
    {
      "_tag": "Pointer",
      "path": [
        "string"
      ],
      "message": "string"
    }
  ],
  "message": "string",
  "_tag": "HttpApiDecodeError"
}

{
  "code": "authentication_required",
  "message": "Authentication required. Send Authorization: Bearer <api-key>, x-api-key, or a signed-in session."
}

{
  "code": "not_found",
  "message": "The requested resource was not found."
}

{
  "code": "conflict",
  "message": "The requested resource already exists."
}

{
  "code": "internal_error",
  "message": "An unexpected server error occurred."
}

Create workspace API key

Request Body

Response Body

201application/json

400application/json

401application/json

404application/json

409application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`