Coder accounts

Connected subscriptions and custom API keys for native coders.

See the OpenAPI document for schemas and operation IDs.

Prerequisites

• Protected operations require an API key in x-api-key or a browser session cookie; some actions require a verified user session
• Tenant-scoped operations use X-Organization-Id; browser sessions can use their active workspace. Discovery and personal-workspace bootstrap do not require an active workspace
• The base URL for your deployment, https://server.hlix.ai by default

Operations

Method	Path	Operation
GET	/v1/api/coder-accounts	List safe coder accounts
POST	/v1/api/coder-accounts	Import a subscription credential or custom API key
DELETE	/v1/api/coder-accounts/{id}	Remove an account and its credential
PATCH	/v1/api/coder-accounts/{id}	Rename, share or enable an account
PUT	/v1/api/coder-accounts/{id}/credential	Replace an account credential
GET	/v1/api/coder-accounts/{id}/models	Read cached models advertised by an account
POST	/v1/api/coder-accounts/{id}/models/refresh	Refresh an API account’s advertised models
POST	/v1/api/coder-accounts/{id}/test	Check a Claude or Codex API key
POST	/v1/api/coder-accounts/connect	Start subscription sign-in
DELETE	/v1/api/coder-accounts/connect/{sessionId}	Cancel subscription sign-in
POST	/v1/api/coder-accounts/connect/{sessionId}/complete	Finish subscription sign-in or poll device authorization

List safe coder accounts

GET /v1/api/coder-accounts · operation ID listCoderAccounts

Parameters

Name	In	Required	Type	Description
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
200	CoderAccount[]	Members see their own and shared accounts; owners/admins see all. Credentials are never returned.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner’s consent.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

Import a subscription credential or custom API key

POST /v1/api/coder-accounts · operation ID createCoderAccount

Parameters

Name	In	Required	Type	Description
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Request body — application/json, CreateCoderAccount (required)

Property	Type	Required	Notes
baseUrl	string (uri)	no
coder	claude-code | codex	yes
credential	string	yes	min length 1, max length 20000
kind	subscription | api_key	yes
label	string	yes	min length 1, max length 80
shared	boolean	no

Responses

Status	Body	Description
201	CoderAccount	Connected account. Subscription defaults to private ownership.
400	ValidationError | ApiError	Invalid body or credential, or unsupported account operation.
401	ApiError	No valid session or API key.
403	ApiError	Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner’s consent.
404	ApiError	The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
409	ApiError	The session is already connected or the account is running a task.

Remove an account and its credential

DELETE /v1/api/coder-accounts/{id} · operation ID deleteCoderAccount

Parameters

Name	In	Required	Type	Description
id	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
200	DeletedAck	Removed. A named pin will remain unavailable until explicitly changed.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner’s consent.
404	ApiError	No such account visible in this workspace.
409	ApiError	The session is already connected or the account is running a task.

Rename, share or enable an account

PATCH /v1/api/coder-accounts/{id} · operation ID updateCoderAccount

Parameters

Name	In	Required	Type	Description
id	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Request body — application/json, PatchCoderAccount (required)

Property	Type	Required	Notes
enabled	boolean	no
label	string	no	min length 1, max length 80
shared	boolean	no

Responses

Status	Body	Description
200	CoderAccount	Updated account.
400	ValidationError | ApiError	Invalid body or credential, or unsupported account operation.
401	ApiError	No valid session or API key.
403	ApiError	Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner’s consent.
404	ApiError	No such account visible in this workspace.
409	ApiError	The session is already connected or the account is running a task.

Replace an account credential

PUT /v1/api/coder-accounts/{id}/credential · operation ID reconnectCoderAccount

Parameters

Name	In	Required	Type	Description
id	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Request body — application/json, ReconnectCoderAccount (required)

Property	Type	Required	Notes
baseUrl	string (uri) | null	no
credential	string	yes	min length 1, max length 20000

Responses

Status	Body	Description
200	CoderAccount	Reconnected account with the same coder and kind.
400	ValidationError | ApiError	Invalid body or credential, or unsupported account operation.
401	ApiError	No valid session or API key.
403	ApiError	Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner’s consent.
404	ApiError	No such account visible in this workspace.
409	ApiError	The session is already connected or the account is running a task.

Read cached models advertised by an account

GET /v1/api/coder-accounts/{id}/models · operation ID getCoderAccountModels

Parameters

Name	In	Required	Type	Description
id	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
200	CoderAccountModelCatalog	Advertised models, not proof of entitlement. Never probes the provider.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner’s consent.
404	ApiError	No such account visible in this workspace.

Refresh an API account’s advertised models

POST /v1/api/coder-accounts/{id}/models/refresh · operation ID refreshCoderAccountModels

Parameters

Name	In	Required	Type	Description
id	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
200	CoderAccountModelCatalog	Cached API model list. Subscription menus come from normal native sessions.
400	ValidationError | ApiError	Invalid body or credential, or unsupported account operation.
401	ApiError	No valid session or API key.
403	ApiError	Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner’s consent.
404	ApiError	No such account visible in this workspace.
409	ApiError	The session is already connected or the account is running a task.
502	ApiError	Provider model list unavailable.

Check a Claude or Codex API key

POST /v1/api/coder-accounts/{id}/test · operation ID testCoderAccount

Parameters

Name	In	Required	Type	Description
id	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
200	CoderAccountProbe	API key check succeeded.
400	ValidationError | ApiError	Invalid body or credential, or unsupported account operation.
401	ApiError	No valid session or API key.
403	ApiError	Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner’s consent.
404	ApiError	No such account visible in this workspace.
502	CoderAccountProbe	Provider check failed; safe details only.

Start subscription sign-in

POST /v1/api/coder-accounts/connect · operation ID startCoderAccountConnect

Parameters

Name	In	Required	Type	Description
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Request body — application/json, StartCoderConnect (required)

Property	Type	Required	Notes
accountId	string (uuid)	no
callbackPort	integer	no	min 1024, max 65535
coder	claude-code | codex	yes
label	string	yes	min length 1, max length 80
shared	boolean	no

Responses

Status	Body	Description
201	CoderConnect	Provider authorization instructions. Expires after ten minutes.
400	ValidationError | ApiError	Invalid body or credential, or unsupported account operation.
401	ApiError	No valid session or API key.
403	ApiError	Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner’s consent.
404	ApiError	No such account visible in this workspace.
409	ApiError	The session is already connected or the account is running a task.
502	ApiError	Provider unavailable.

Cancel subscription sign-in

DELETE /v1/api/coder-accounts/connect/{sessionId} · operation ID cancelCoderAccountConnect

Parameters

Name	In	Required	Type	Description
sessionId	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status	Body	Description
200	DeletedAck	Cancelled.
400	ApiError	The request named no active organization.
401	ApiError	No valid session or API key.
403	ApiError	Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner’s consent.
404	ApiError	No such account visible in this workspace.
409	ApiError	The session is already connected or the account is running a task.

Finish subscription sign-in or poll device authorization

POST /v1/api/coder-accounts/connect/{sessionId}/complete · operation ID completeCoderAccountConnect

Parameters

Name	In	Required	Type	Description
sessionId	path	yes	string
X-Organization-Id	header	no	string	The workspace (organization) to act in. Omitted, the session’s active organization is used.

Request body — application/json, CompleteCoderConnect (required)

Property	Type	Required	Notes
code	string	no	min length 1, max length 4096

Responses

Status	Body	Description
200	CoderConnectResult	Pending authorization or connected account ID. Never returns credentials.
400	ValidationError | ApiError	Invalid body or credential, or unsupported account operation.
401	ApiError	No valid session or API key.
403	ApiError	Agency roles only. API keys require owner/admin; subscription sharing and reconnect require its owner’s consent.
404	ApiError	No such account visible in this workspace.
409	ApiError	The session is already connected or the account is running a task.
502	ApiError	Provider unavailable.

If a request fails

The response table for each operation lists its documented errors. Common status codes include:

• 400 — the body failed schema validation, or the request named no active organization. A ValidationError body carries the failing fields; an ApiError body carries only error.
• 401 — no valid session or API key.
• 403 — authenticated, but not a member of the named organization, or a client collaborator without the required access.
• 404 — check the resource ID and your access to the selected Workspace.
• 409 — the expected revision or state is stale, or another operation currently owns the transition.
• 500 — the operation failed server-side. Retry only where an idempotency key makes that safe.

Next steps

API reference

Browse endpoints, request fields and responses.

API & OpenAPI

Download the contract, generate a client, and read the compatibility policy.

TypeScript SDK

Auth, retries, typed errors, uploads and streaming, already built.

CLI reference

The same operations from a terminal, with a stable JSON envelope.