Authentication

Flow accepts two auth methods: an organization API key for developer-to-Flow access, and a player JWT for end-user-to-Flow access.

Pick the right method

API key (this page) is right when you are the caller — back-office tools, historical data pulls, partner integrations, market-making strategies. One key per organization, one rate-limit bucket.

Player JWT is right when each of your users needs their own balances and connected venues — mobile apps, consumer-facing web clients, agents acting on behalf of a logged-in human. See /developers/end-user-auth.

Every endpoint under /flow/v1/* accepts either header. If you send both, the API key wins.

API key format

Keys are 45 characters long and use a prefix convention:

text

om_data_live_<32 random base64url characters>

om_        OpenMarkets
data       key type (data keys grant read access)
live       environment (live vs. future test sandbox)
...        the secret material itself

The prefix is safe to log (e.g. om_data_live_a7Kpq2) — you can use it to identify keys in dashboards. The full plaintext is a secret and should be treated like a password.

Passing the key

REST requests authenticate with the X-API-Key header:

bash

curl https://api.openmarkets.ai/flow/v1/contests \
  -H "X-API-Key: om_data_live_..."

WebSocket connections pass the key as a query parameter (headers aren't universally supported on WS handshakes in browsers):

text

wss://api.openmarkets.ai/flow/v1/stream?api_key=om_data_live_...

Plaintext is shown only once

We do not store the plaintext of your API key. The OpenMarkets backend only persists a SHA-256 hash. When a key is created, the plaintext is displayed once — if it's lost, the only option is to revoke and re-issue.

Error responses

When authentication fails, the API returns HTTP 401 with a structured body:

json

{
  "error": {
    "code": "missing_credentials",
    "message": "Missing X-API-Key header or Authorization: Bearer <jwt>"
  }
}

Possible codes: missing_credentials (neither header present), invalid_api_key (unknown, revoked, or expired API key), invalid_jwt (bearer token signature failed or expired).

Revoking a key

If a key is compromised, contact james@openmarkets.ai immediately. Revocation takes effect within 60 seconds (the auth cache TTL). Once revoked, any further requests with that key will return invalid_api_key.

Best practices

Store keys in a secret manager, not in source control.
Use separate keys per environment (staging vs. production) so you can revoke one without breaking the other.
Rotate keys on a schedule and whenever an employee with access leaves.
If you must embed a key in client-side code, treat the entire app surface as public and limit what that key can do via its per-key rate limits.