> For the complete documentation index, see [llms.txt](https://ocx.gitbook.io/ocx-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ocx.gitbook.io/ocx-doc/ocx/authentication/overview.md).

# overview

OCX supports three ways to authenticate. Pick the right one for your use case.

{% stepper %}
{% step %}

### Session cookie (for the web UI)

When you sign in via the web app using SIWE, OCX sets a secure httpOnly cookie (`astra_session`) containing a JWT. Your browser sends this cookie automatically with every API call.

* **Transport**: cookie.
* **Lifetime**: 7 days.
* **Best for**: interactive use in the browser.
* **Revocation**: `POST /auth/logout` or clearing cookies.
  {% endstep %}

{% step %}

### Bearer token (raw JWT)

If you need to authenticate from a backend that already handled SIWE itself, you can extract the JWT from the `astra_session` cookie and send it as a Bearer token on subsequent requests.

```http
Authorization: Bearer eyJhbGciOi...
```

* **Transport**: `Authorization` header.
* **Lifetime**: same as the session (7 days).
* **Best for**: backends proxying authenticated users.
  {% endstep %}

{% step %}

### API keys (for bots and integrations)

API keys are the recommended mechanism for any programmatic access that isn't tied to an interactive login.

```http
Authorization: Bearer ocx_sk_...
```

* **Transport**: `Authorization` header.
* **Lifetime**: you choose — permanent, or auto-expiring after N days.
* **Scope**: `read` (data only) or `trade` (data + write).
* **Restrictions**: optional IP allowlist.
* **Revocation**: instant, from the API or Portfolio → API Keys UI.

See [API Keys](broken://pages/3ef96c2ed737e95650fc76935ee64849bace54f3) for details.
{% endstep %}
{% endstepper %}

## Precedence

If both a cookie and an `Authorization` header are present, the `Authorization` header wins. This lets you override a stale session cookie without signing out first.

## Which routes need which credentials?

| Route pattern                                                        | Cookie / JWT | `read` API key | `trade` API key |
| -------------------------------------------------------------------- | :----------: | :------------: | :-------------: |
| Public market data (`GET /perps/markets`, `/markets/board`, etc.)    |       ✓      |        ✓       |        ✓        |
| Account reads (`GET /perps/positions`, `/wallet/balance`, etc.)      |       ✓      |        ✓       |        ✓        |
| Order & quote placement (`POST /perps/orders`, `/quotes/bulk`, etc.) |       ✓      |        ✗       |        ✓        |
| Wallet actions (`POST /wallet/withdraw`, `/wallet/transfer`)         |       ✓      |        ✗       |        ✓        |
| **API key management** (`/perps/me/api-keys*`)                       |       ✓      |        ✗       |        ✗        |

API key management is intentionally session-only: an API key cannot mint or revoke other keys.

## Failures

* `401 Unauthorized` — no credential, or the credential is expired, invalid, or revoked.
* `403 Forbidden` — the credential is valid but doesn't grant the needed scope, or the caller's IP isn't in the key's allowlist.

See [Error Codes](file:///7302513/reference/error-codes.md) for full error semantics.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ocx.gitbook.io/ocx-doc/ocx/authentication/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.