# Create workspace API key (/docs/api-reference/workspaces/post-api-v1-workspaces-workspacehandle-api-keys)

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

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.

Tags: Workspaces

Operation ID: `workspaces.createWorkspaceApiKey`

### Authentication

- `andibaseKey` | type: `apiKey` | in: `header` | name: `x-api-key`

  Authentication is required. Send an API key in x-api-key. The HTTP API also accepts Authorization: Bearer <api-key> and first-party session auth. Agent-login keys are workspace-scoped and reusable until revoked or their configured expiration.

### Request Body

Required: yes

Request Formats

#### Media Type: `application/json`

Schema

schema: `CreateWorkspaceApiKeyInput` | type: `object`

Payload to create a workspace API key for the current user. Effective access is the union of role permissions and explicit permissions. If neither is provided, role defaults to admin.

Fields

- object | required | schema: `CreateWorkspaceApiKeyInput` | Payload to create a workspace API key for the current user. Effective access is the union of role permissions and explicit permissions. If neither is provided, role defaults to admin.

  - `name` | string | required | schema: `NonEmptyString` | minLength: 1 | a non empty string

  - `role` | string | optional | schema: `AssignableApiKeyRole` | enum: admin, editor, viewer | Hardcoded role available for new workspace API keys

  - `permissions` | object | optional | schema: `WorkspaceApiKeyPermissions` | Explicit permissions attached directly to the API key. Effective access is the union of role permissions and these permissions.

    - `additionalProperties` | array | optional | minItems: 1 | an array of at least 1 item(s)

      - `items` | string | required | schema: `NonEmptyString` | minLength: 1 | a non empty string

  - `expiresInMs` | integer | optional | a positive number

Examples

#### Example 1

```json
{
  "name": "Workspace integration key",
  "role": "admin",
  "permissions": {
    "channels": [
      "read",
      "write"
    ],
    "messages": [
      "read",
      "write"
    ],
    "threads": [
      "read",
      "write"
    ]
  },
  "expiresInMs": 2592000000
}
```

Examples

#### Example 1

```json
{
  "name": "Workspace integration key",
  "role": "admin",
  "permissions": {
    "channels": [
      "read",
      "write"
    ],
    "messages": [
      "read",
      "write"
    ],
    "threads": [
      "read",
      "write"
    ]
  },
  "expiresInMs": 2592000000
}
```

### Responses

#### 201

Success

Response Formats

#### Media Type: `application/json`

Schema

type: `object`

Fields

- object | required

  - `key` | string | required

  - `apiKey` | object | required | schema: `WorkspaceApiKey` | Workspace-scoped API key metadata

    - `id` | string | required

    - `name` | anyOf | required

      - `anyOf[0]` | string | required

      - `anyOf[1]` | null | required

    - `start` | anyOf | required

      - `anyOf[0]` | string | required

      - `anyOf[1]` | null | required

    - `prefix` | anyOf | required

      - `anyOf[0]` | string | required

      - `anyOf[1]` | null | required

    - `enabled` | boolean | required

    - `role` | string | required | schema: `ApiKeyRole` | enum: admin, editor, viewer, custom | Resolved role for a workspace API key. Legacy keys may appear as custom.

    - `permissions` | anyOf | required

      - `anyOf[0]` | object | required | schema: `WorkspaceApiKeyPermissions` | Explicit permissions attached directly to the API key. Effective access is the union of role permissions and these permissions.

      - `anyOf[1]` | null | required

    - `createdAt` | string | required

    - `updatedAt` | string | required

    - `expiresAt` | anyOf | required

      - `anyOf[0]` | string | required

      - `anyOf[1]` | null | required

    - `lastRequest` | anyOf | required

      - `anyOf[0]` | string | required

      - `anyOf[1]` | null | required

Examples

#### Example 1

```json
{
  "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
  }
}
```

Examples

#### Example 1

```json
{
  "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
  }
}
```

#### 400

The request did not match the expected schema

Response Formats

#### Media Type: `application/json`

Schema

type: `anyOf`

Fields

- anyOf | required

  - `anyOf[0]` | object | required | schema: `HttpApiDecodeError` | The request did not match the expected schema

    - `issues` | array | required

      - `items` | object | required | schema: `Issue` | Represents an error encountered while parsing a value to match the schema

    - `message` | string | required

    - `_tag` | string | required | enum: HttpApiDecodeError

  - `anyOf[1]` | object | required

    - `code` | string | required | enum: invalid_request, workspace_context_required

    - `message` | string | required

    - `details` | object | optional | schema: `ApiErrorDetails` | Optional machine-readable error details

      - `additionalProperties` | string | optional

#### 401

Error

Response Formats

#### Media Type: `application/json`

Schema

type: `object`

Fields

- object | required

  - `code` | string | required | enum: authentication_required, invalid_api_key, session_required

  - `message` | string | required

  - `details` | object | optional | schema: `ApiErrorDetails` | Optional machine-readable error details

    - `additionalProperties` | string | optional

Examples

#### Example 1

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

#### Example 2

```json
{
  "code": "invalid_api_key",
  "message": "The provided API key is invalid, expired, revoked, or malformed."
}
```

Examples

#### Example 1

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

#### Example 2

```json
{
  "code": "invalid_api_key",
  "message": "The provided API key is invalid, expired, revoked, or malformed."
}
```

#### 404

Error

Response Formats

#### Media Type: `application/json`

Schema

type: `object`

Fields

- object | required

  - `code` | string | required | enum: not_found

  - `message` | string | required

  - `details` | object | optional | schema: `ApiErrorDetails` | Optional machine-readable error details

    - `additionalProperties` | string | optional

Examples

#### Example 1

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

Examples

#### Example 1

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

#### 409

Error

Response Formats

#### Media Type: `application/json`

Schema

type: `object`

Fields

- object | required

  - `code` | string | required | enum: conflict

  - `message` | string | required

  - `details` | object | optional | schema: `ApiErrorDetails` | Optional machine-readable error details

    - `additionalProperties` | string | optional

Examples

#### Example 1

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

Examples

#### Example 1

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

#### 500

Error

Response Formats

#### Media Type: `application/json`

Schema

type: `object`

Fields

- object | required

  - `code` | string | required | enum: internal_error

  - `message` | string | required

  - `details` | object | optional | schema: `ApiErrorDetails` | Optional machine-readable error details

    - `additionalProperties` | string | optional

Examples

#### Example 1

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

Examples

#### Example 1

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

## Documentation Navigation
Use these paths to traverse the relevant docs and generated API reference files for the app.
- Create workspace API key [current] -> `/docs/api-reference/workspaces/post-api-v1-workspaces-workspacehandle-api-keys`
- andibase Overview -> `/docs` (source: `content/docs/index.mdx`)
- Get started (for AI Agents) -> `/docs/agent-get-started` (source: `content/docs/agent-get-started.mdx`)
- Agent Tools -> `/docs/agent-tools` (source: `content/docs/agent-tools.mdx`)
- Agents -> `/docs/agents` (source: `content/docs/agents.mdx`)
- Agent Auth -> `/docs/api-reference/agent-auth`
- Get agent login request -> `/docs/api-reference/agent-auth/get-api-v1-agent-auth-requests-usercode`
- Exchange agent login -> `/docs/api-reference/agent-auth/post-api-v1-agent-auth-exchange`
- Start agent login -> `/docs/api-reference/agent-auth/post-api-v1-agent-auth-requests`
- Approve agent login -> `/docs/api-reference/agent-auth/post-api-v1-agent-auth-requests-usercode-approve`
- Deny agent login -> `/docs/api-reference/agent-auth/post-api-v1-agent-auth-requests-usercode-deny`
- Agents -> `/docs/api-reference/agents`
- Delete workspace agent -> `/docs/api-reference/agents/delete-api-v1-agents-id`
- List workspace agents -> `/docs/api-reference/agents/get-api-v1-agents`
- Get workspace agent -> `/docs/api-reference/agents/get-api-v1-agents-id`
- List agent chats -> `/docs/api-reference/agents/get-api-v1-agents-id-chats`
- Get agent chat -> `/docs/api-reference/agents/get-api-v1-agents-id-chats-chatid`
- Update workspace agent -> `/docs/api-reference/agents/patch-api-v1-agents-id`
- Create workspace agent -> `/docs/api-reference/agents/post-api-v1-agents`
- Send agent message -> `/docs/api-reference/agents/post-api-v1-agents-id-chats-chatid-messages`
- Apps -> `/docs/api-reference/apps`
- Delete app -> `/docs/api-reference/apps/delete-api-v1-apps-id`
- List workspace apps -> `/docs/api-reference/apps/get-api-v1-apps`
- Get app by id -> `/docs/api-reference/apps/get-api-v1-apps-id`
- Update app -> `/docs/api-reference/apps/patch-api-v1-apps-id`
- Create app -> `/docs/api-reference/apps/post-api-v1-apps`
- Automations -> `/docs/api-reference/automations`
- Delete workspace automation -> `/docs/api-reference/automations/delete-api-v1-automations-id`
- List workspace automations -> `/docs/api-reference/automations/get-api-v1-automations`
- Get workspace automation -> `/docs/api-reference/automations/get-api-v1-automations-id`
- List automation runs -> `/docs/api-reference/automations/get-api-v1-automations-id-runs`
- Get automation run -> `/docs/api-reference/automations/get-api-v1-automations-id-runs-runid`
- Update workspace automation -> `/docs/api-reference/automations/patch-api-v1-automations-id`
- Create workspace automation -> `/docs/api-reference/automations/post-api-v1-automations`
- Run automation -> `/docs/api-reference/automations/post-api-v1-automations-id-run`
- Trigger automation webhook -> `/docs/api-reference/automations/post-api-v1-automations-webhooks-publicid-secret`
- Channels -> `/docs/api-reference/channels`
- Delete channel -> `/docs/api-reference/channels/delete-api-v1-channels-channelid`
- List channels -> `/docs/api-reference/channels/get-api-v1-channels`
- Get channel -> `/docs/api-reference/channels/get-api-v1-channels-channelid`
- Update channel -> `/docs/api-reference/channels/patch-api-v1-channels-channelid`
- Create channel -> `/docs/api-reference/channels/post-api-v1-channels`
- Data -> `/docs/api-reference/data`
- Data Definitions -> `/docs/api-reference/data-definitions`
- Delete data definition -> `/docs/api-reference/data-definitions/delete-api-v1-data-definitions-id`
- List data definitions -> `/docs/api-reference/data-definitions/get-api-v1-data-definitions`
- Get data definition -> `/docs/api-reference/data-definitions/get-api-v1-data-definitions-id`
- Update data definition -> `/docs/api-reference/data-definitions/patch-api-v1-data-definitions-id`
- Create data definition -> `/docs/api-reference/data-definitions/post-api-v1-data-definitions`
- Data SQL Query -> `/docs/api-reference/data-sql-query`
- Run SQL query against workspace data -> `/docs/api-reference/data-sql-query/post-api-v1-data-sql-query`
- Get data by id -> `/docs/api-reference/data/get-api-v1-data-definitions-definitionid-data-id`
- Select all data row ids -> `/docs/api-reference/data/get-api-v1-data-definitions-definitionid-data-select-all`
- List data -> `/docs/api-reference/data/get-api-v1-data-definitions-definitionid-query`
- Patch many data rows -> `/docs/api-reference/data/patch-api-v1-data-definitions-definitionid-data-patch-many`
- Delete many data rows -> `/docs/api-reference/data/post-api-v1-data-definitions-definitionid-data-delete-many`
- Upsert many data rows -> `/docs/api-reference/data/post-api-v1-data-definitions-definitionid-data-upsert-many`
- DuckDB Query -> `/docs/api-reference/duckdb-query`
- Run a DuckDB query against registered sources -> `/docs/api-reference/duckdb-query/post-api-v1-duckdb-query`
- Explorer -> `/docs/api-reference/explorer`
- Delete explorer folder -> `/docs/api-reference/explorer/delete-api-v1-workspace-nodes-nodeid`
- List explorer nodes -> `/docs/api-reference/explorer/get-api-v1-workspace-nodes`
- List explorer folders -> `/docs/api-reference/explorer/get-api-v1-workspace-nodes-folders`
- Rename explorer folder -> `/docs/api-reference/explorer/patch-api-v1-workspace-nodes-nodeid-rename`
- Create folder -> `/docs/api-reference/explorer/post-api-v1-workspace-nodes-folders`
- Move explorer node -> `/docs/api-reference/explorer/post-api-v1-workspace-nodes-nodeid-move`
- Files -> `/docs/api-reference/files`
- List workspace files -> `/docs/api-reference/files/get-api-v1-files`
- Read file content -> `/docs/api-reference/files/get-api-v1-files-fileid-content`
- Create file -> `/docs/api-reference/files/post-api-v1-files`
- Complete file upload -> `/docs/api-reference/files/post-api-v1-files-fileid-complete`
- Presign multipart parts -> `/docs/api-reference/files/post-api-v1-files-fileid-parts`
- Update file content -> `/docs/api-reference/files/put-api-v1-files-fileid-content`
- Messages -> `/docs/api-reference/messages`
- List channel messages -> `/docs/api-reference/messages/get-api-v1-channels-channelid-messages`
- List thread messages -> `/docs/api-reference/messages/get-api-v1-channels-channelid-threads-threadid-messages`
- Create channel message -> `/docs/api-reference/messages/post-api-v1-channels-channelid-messages`
- Create thread message -> `/docs/api-reference/messages/post-api-v1-channels-channelid-threads-threadid-messages`
- Notifications -> `/docs/api-reference/notifications`
- List notification devices -> `/docs/api-reference/notifications/get-api-v1-notifications-devices`
- Check Expo notification receipts -> `/docs/api-reference/notifications/post-api-v1-notifications-receipts`
- Send workspace notifications -> `/docs/api-reference/notifications/post-api-v1-notifications-send`
- Runs -> `/docs/api-reference/runs`
- List workspace runs -> `/docs/api-reference/runs/get-api-v1-runs`
- Get workspace run -> `/docs/api-reference/runs/get-api-v1-runs-runid`
- Threads -> `/docs/api-reference/threads`
- List channel threads -> `/docs/api-reference/threads/get-api-v1-channels-channelid-threads`
- Get thread -> `/docs/api-reference/threads/get-api-v1-channels-channelid-threads-threadid`
- Create thread -> `/docs/api-reference/threads/post-api-v1-channels-channelid-threads`
- Workflows -> `/docs/api-reference/workflows`
- Delete workflow definition -> `/docs/api-reference/workflows/delete-api-v1-workflows-id`
- List workflow definitions -> `/docs/api-reference/workflows/get-api-v1-workflows`
- Get workflow definition -> `/docs/api-reference/workflows/get-api-v1-workflows-id`
- Update workflow definition -> `/docs/api-reference/workflows/patch-api-v1-workflows-id`
- Create workflow definition -> `/docs/api-reference/workflows/post-api-v1-workflows`
- Workspaces -> `/docs/api-reference/workspaces`
- Delete workspace API key -> `/docs/api-reference/workspaces/delete-api-v1-workspaces-workspacehandle-api-keys-keyid`
- Delete workspace credential -> `/docs/api-reference/workspaces/delete-api-v1-workspaces-workspacehandle-credentials-credentialid`
- Delete workspace invitation -> `/docs/api-reference/workspaces/delete-api-v1-workspaces-workspacehandle-invitations-invitationid`
- Delete workspace user -> `/docs/api-reference/workspaces/delete-api-v1-workspaces-workspacehandle-users-userid`
- List my workspaces -> `/docs/api-reference/workspaces/get-api-v1-workspaces`
- List workspace API keys -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-api-keys`
- List workspace credentials -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-credentials`
- List workspace credential tools -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-credentials-credentialid-tools`
- List workspace invitations -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-invitations`
- List workspace users -> `/docs/api-reference/workspaces/get-api-v1-workspaces-workspacehandle-users`
- Create workspace -> `/docs/api-reference/workspaces/post-api-v1-workspaces`
- Create workspace credential -> `/docs/api-reference/workspaces/post-api-v1-workspaces-workspacehandle-credentials`
- Invite user to workspace -> `/docs/api-reference/workspaces/post-api-v1-workspaces-workspacehandle-invitations`
- Create workspace user -> `/docs/api-reference/workspaces/post-api-v1-workspaces-workspacehandle-users`
- Apps -> `/docs/apps` (source: `content/docs/apps.mdx`)
- Authentication -> `/docs/authentication` (source: `content/docs/authentication.mdx`)
- Building Blocks -> `/docs/building-blocks` (source: `content/docs/building-blocks.mdx`)
- Data Model -> `/docs/data-model` (source: `content/docs/data-model.mdx`)
- Embedded Host Actions -> `/docs/embedded-host-actions` (source: `content/docs/embedded-host-actions.mdx`)
- Introduction -> `/docs/introduction` (source: `content/docs/introduction.mdx`)
- Recipes -> `/docs/receipes` (source: `content/docs/receipes/index.mdx`)
- Construction Site Visit Agent -> `/docs/receipes/construction-site-visit-agent` (source: `content/docs/receipes/construction-site-visit-agent.mdx`)
- Daily Lead Qualification Agent -> `/docs/receipes/daily-lead-qualification-agent` (source: `content/docs/receipes/daily-lead-qualification-agent.mdx`)
- Day Planner Agent -> `/docs/receipes/day-planner-agent` (source: `content/docs/receipes/day-planner-agent.mdx`)
- Expense Tracker -> `/docs/receipes/expense-tracker` (source: `content/docs/receipes/expense-tracker.mdx`)
- Legal Case Tracker -> `/docs/receipes/legal-case-tracker` (source: `content/docs/receipes/legal-case-tracker.mdx`)
- Spare Parts Request Agent -> `/docs/receipes/spare-parts-request-agent` (source: `content/docs/receipes/spare-parts-request-agent.mdx`)
- Weekly Report Email Agent -> `/docs/receipes/weekly-report-email-agent` (source: `content/docs/receipes/weekly-report-email-agent.mdx`)
- UI Components -> `/docs/ui-components` (source: `content/docs/ui-components.mdx`)