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:
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.
Market Data WebSocket
The socket authenticates by message once it is open — never in the handshake:
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 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.