# Coder accounts

Connected subscriptions and custom API keys for native coders.

See the [OpenAPI document](/openapi.json) 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](#list-safe-coder-accounts) |
| `POST` | `/v1/api/coder-accounts` | [Import a subscription credential or custom API key](#import-a-subscription-credential-or-custom-api-key) |
| `DELETE` | `/v1/api/coder-accounts/{id}` | [Remove an account and its credential](#remove-an-account-and-its-credential) |
| `PATCH` | `/v1/api/coder-accounts/{id}` | [Rename, share or enable an account](#rename-share-or-enable-an-account) |
| `PUT` | `/v1/api/coder-accounts/{id}/credential` | [Replace an account credential](#replace-an-account-credential) |
| `GET` | `/v1/api/coder-accounts/{id}/models` | [Read cached models advertised by an account](#read-cached-models-advertised-by-an-account) |
| `POST` | `/v1/api/coder-accounts/{id}/models/refresh` | [Refresh an API account's advertised models](#refresh-an-api-accounts-advertised-models) |
| `POST` | `/v1/api/coder-accounts/{id}/test` | [Check a Claude or Codex API key](#check-a-claude-or-codex-api-key) |
| `POST` | `/v1/api/coder-accounts/connect` | [Start subscription sign-in](#start-subscription-sign-in) |
| `DELETE` | `/v1/api/coder-accounts/connect/{sessionId}` | [Cancel subscription sign-in](#cancel-subscription-sign-in) |
| `POST` | `/v1/api/coder-accounts/connect/{sessionId}/complete` | [Finish subscription sign-in or poll device authorization](#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](/api/reference/)
  [API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)
  [CLI reference](/reference/cli/)