# Codex session

GET | POST | DELETE /v1/organizations/codex-session - Codex connection status, connect, disconnect.

*ProxyLLM docs · https://proxyllm.ai/docs/api/codex-session*

```
GET    /v1/organizations/codex-session
POST   /v1/organizations/codex-session
DELETE /v1/organizations/codex-session
```

Auth: **[account token](/docs/api/authentication)**. `rk_` or `sk_` can read status; POST and DELETE need `sk_`. This is the endpoint `npx proxyllm codex connect` drives ([Connect Codex](/docs/codex)).

## Status

```bash
curl https://api.proxyllm.ai/v1/organizations/codex-session \
  -H "Authorization: Bearer rk_your_readonly_token"
```

```json
{
  "connected": true,
  "status": "connected",
  "connected_at": "2026-06-01T10:00:00.000Z",
  "last_used_at": "2026-07-03T09:12:00.000Z",
  "expires_at": null,
  "last_error": null
}
```

`status` is `connected` when the Codex lane can serve; other values (`pending`, `connecting`, `expired`, `revoked`, `error`) mean it can't, and `last_error` says why.

## Connect

Uploads a Codex sign-in (the contents of `~/.codex/auth.json` from a machine where Codex is signed in) and provisions it so your routing keys' Codex lanes can serve.

```bash
curl -X POST https://api.proxyllm.ai/v1/organizations/codex-session \
  -H "Authorization: Bearer sk_your_account_token" \
  -H "Content-Type: application/json" \
  -d '{"auth_json": { ...contents of auth.json... }}'
```

Request body:

| Field         | Type             | Notes                                                            |
| ------------- | ---------------- | ---------------------------------------------------------------- |
| `auth_json`   | object, required | The parsed `auth.json` from the Codex CLI. Stored encrypted.     |
| `source_path` | string           | Optional, where it came from, for your own records.              |
| `ttl_seconds` | number           | Optional; marks the sign-in as expiring after this many seconds. |

Response:

```json
{
  "connected": true,
  "status": "connected",
  "connected_at": "2026-07-03T10:00:00.000Z",
  "last_used_at": "2026-07-03T10:00:00.000Z",
  "expires_at": null,
  "last_error": null,
  "codex_host": {
    "provisioned": true,
    "account_status": "active"
  }
}
```

`codex_host.provisioned` false means the sign-in is stored but the serving backend couldn't be prepared; `last_error` carries the reason, and requests on the Codex lane will fail until it resolves (usually by reconnecting).

## Disconnect

```bash
curl -X DELETE https://api.proxyllm.ai/v1/organizations/codex-session \
  -H "Authorization: Bearer sk_your_account_token"
```

```json
{ "connected": false, "status": "revoked" }
```

Removes the stored sign-in and deprovisions the backend. Codex lanes stop serving until you connect again.

## Errors

| Status | Code                    | When                                 |
| ------ | ----------------------- | ------------------------------------ |
| 400    | `bad_request`           | `auth_json` missing on POST.         |
| 401    | (none)                  | No token sent.                       |
| 401    | `invalid_account_token` | Unknown or revoked token.            |
| 403    | `read_only_token`       | POST or DELETE with an `rk_` token.  |
| 405    | `method_not_allowed`    | Method other than GET, POST, DELETE. |
| 500    | `encrypt_failed`        | Encrypting the sign-in failed.       |
| 500    | `server_error`          | The database write failed.           |