> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.immix.xyz/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.immix.xyz/_mcp/server.

# Authentication

Every call to the Immix API carries a bearer token: a JWT, issued by Immix's identity provider,
for a person or a machine client of your organisation. The token only authenticates — it names
your organisation and you. What you may do is decided by the platform's records at the time of
each request: your organisation's status and your user's capabilities, never anything written on
the token.

## Getting a token

Immix sets up your organisation's access during onboarding. People sign in through Immix's
identity provider; a machine client uses the OAuth 2.0 client-credentials grant and acts as a
service user of your organisation. The token endpoint and the audience for each environment come
with your onboarding.

## REST API

Send the token on every request:

```http
Authorization: Bearer <token>
```

Read `GET /me` first. It tells you who the platform holds you to be: your user, your
organisation, and your capabilities. Configure a client from it, never from the token's claims.

The first request you make registers you with the platform. Until an administrator of your
organisation admits you — by granting you capabilities — every route but `GET /me` answers
`403 AWAITING_ADMISSION`, and `GET /me` serves your row so a client can show that you are waiting.
Every answer the platform can give before it reads your request is in the REST API guide's
[Authentication and admission](/guides/rest-api-guide#authentication-and-admission).

## Market Data WebSocket

The socket authenticates by message once it is open — never in the handshake:

```json
{"op": "auth", "reqId": "auth-1", "params": {"token": "<token>"}}
```

Wait for the acknowledgement before you subscribe: `"success": true`, or `"success": false` with
`"error": "invalid_token"`. The gateway checks the token's signature, its validity window (`exp`
and `nbf`), and the audience and issuer your environment is configured with. The
[Quickstart](/guides/quickstart) walks the whole exchange.

## Keeping tokens safe

* Never log a token, whole or in part, at any level.
* Keep machine credentials out of source code: read them from the environment or a secret store.
* A token is a credential for your whole user: send it only to the Immix endpoints your onboarding
  names.