Add an AI account from a pasted key, for the workspace or for yourself

POST

/connections/ai-accounts/connect

• Production

Constraints not expressible in JSON Schema, enforced at runtime:

• An engine-account label must not begin or end with whitespace and must contain no control characters (U+0000–U+001F, U+007F).

May require, depending on the request: connections.write, connections.org.write

Authorizations

• bearerAuth

Parameters

Header Parameters

x-uai-org

string

Org scope: me or an org slug. Absent means the caller’s active/personal org. It selects the workspace used for permission checks and for most resource filters; operation-specific access rules still apply.

Request Body ^required

Any of:

object

object

scope

required

org: the workspace’s accounts, used by every member’s tasks; me: the caller’s own, in this workspace.

string

Allowed values: org me

engine

required

string

Allowed values: claude codex grok cursor

label

required

string

>= 1 characters <= 64 characters

secret

required

The pasted key or token. Write-only.

string

>= 1 characters <= 8192 characters

accountId

Sign in again to this existing account instead of adding one.

string

>= 1 characters <= 128 characters

object

object

mode

required

string

scope

required

org: the workspace’s accounts, used by every member’s tasks; me: the caller’s own, in this workspace.

string

Allowed values: org me

label

required

string

>= 1 characters <= 64 characters

providerType

required

openrouter: an OpenRouter key; bedrock: an Amazon Bedrock API key; custom: any endpoint that speaks the engine’s protocol.

string

Allowed values: openrouter bedrock custom

engine

required

Claude Code or Codex. One connection serves one engine.

string

Allowed values: claude codex

baseUrl

custom only: the https base URL as the engine’s CLI means it (Claude: the API root, no /v1; Codex: the root /responses is appended to). No userinfo, query or fragment. An internal connection may use http.

string

>= 1 characters <= 2048 characters

region

Bedrock only: one AWS region id.

string

>= 1 characters <= 32 characters

transport

Bedrock only: runtime (Claude Code, Codex) or mantle (Codex only).

string

Allowed values: runtime mantle

internal

custom only: “Internal network”, an endpoint reachable only inside your own network (a LAN or private-network gateway). Workspace connections only (scope: "org", added by someone holding connections.org.write). Saved by hand: nothing calls it at save, models are typed, and it runs only on an owned runner serving the workspace. Can’t change on a reconnect.

boolean

secret

required

The provider key. Write-only.

string

>= 1 characters <= 8192 characters

expiresAt

Any of:

integer

integer

null

null

models

The full chosen model list. Required for a new connection; a reconnect keeps the list when omitted.

Array<string>

>= 1 items <= 200 items

discovered

The ids Find models returned, to mark which ids were discovered.

Array<string>

<= 2000 items

defaultModel

string

>= 1 characters <= 200 characters /^[^\s\u0000-\u001f\u007f]+$/

backgroundModel

Any of:

string

string

>= 1 characters <= 200 characters /^[^\s\u0000-\u001f\u007f]+$/

null

null

accountId

Reconnect this connection with a new key. Its URL, engine, provider type, region, transport and internal flag never change.

string

>= 1 characters <= 128 characters

authMode

Internal Claude Code connections only: the header the key is sent in (default bearer). Codex always uses Bearer; any other connection finds it out when the box tests the key.

string

Allowed values: bearer x-api-key

Responses

200

Server-sent event stream for a pasted key’s connect. A custom connection (mode: "custom") answers with JSON instead: { ok: true, accountId } (201) or { ok: false, reason } (422) with a reason code.

string

400

BAD_JSON — the body is not valid JSON, or INVALID_REQUEST — the decoded body does not match the route’s request schema.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

401

UNAUTHORIZED — missing or invalid token, or an org-scoped API key (only user-scoped keys are accepted).

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

402

PLAN_LIMIT — the workspace’s plan does not include API access. Every API-key call can return this; session-token calls never do.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

403

FORBIDDEN (lacking the required permission) or SCOPE_REQUIRED (no workspace, or a membership change in progress).

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

404

SCOPE_REQUIRED — the x-uai-org scope names a workspace that does not exist, or one the caller is not a member of. The two are deliberately indistinguishable: a 403 would confirm the workspace exists.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

413

PAYLOAD_TOO_LARGE — the request body exceeds 16384 bytes.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any

503

SCOPE_REQUIRED — membership reconciliation required, or membership verification unavailable.

object

error

required

object

code

required

Stable, machine-readable error code

string

message

required

Human-readable explanation

string

details

permission

Present on 403 — the permission the caller lacked

string

feature

Present on 402 — gated feature

string

limit

Present on 402 — the plan’s cap

number

plan

Present on 402 — the current plan

string

seats

Present on 402 when the cap is seat-derived

object

seats

required

Effective seats the cap was computed from

integer

seatsMax

required

Any of:

integer

integer

null

null

perSeat

required

Units of the resource each seat carries

number

key

additional properties

any