Authentication

Authorization: Bearer pk_test_...          # sandbox. Live keys are sk_live_...
X-Parity-User: <your own id for this player>
Content-Type: application/json

The funding route in that list is sandbox only and answers 403 sandbox_only for a live operator, along with the other funding routes, the /api/v1/sandbox/* test controls, GET /api/v1/users/{id}/balance and GET /api/v1/users/{id}/ledger. They fund and read a balance held by Parity, which a live operator does not have: its customers' cash is on its own books. The scope exists so a sandbox key can reach them; holding it does not make them reachable in production.

Two routes take no operator key at all, and both are browser surfaces rather than API calls. GET /api/v1/images/{id} serves event artwork from Parity's own origin, because it is an <img src> in a player's browser and a page cannot be handed a secret key. GET /api/v1/stream/prices is an EventSource, for the same reason; it accepts an embed session token, which is not a key, and uses it only to decide whose offering policy filters the feed.

Parity does not authenticate end users, issues them no credentials and knows nothing about them. You have already established who the player is; the header carries your own opaque id for them, and that id is the entire record.

• A write path creates the user on first use. The first quote or order for an id registers it. There is no separate “create player” call to forget.
• A read path never creates one. On the settlement register, the reconciliation feed and the two sandbox balance reads, an id that has never traded is 404 unknown_user rather than an empty page: a typo'd id that returned [] reads as “this player has nothing”, and the mistake surfaces later as a missing credit nobody can explain.
• The order and position lists are the exception. They apply externalUserId as a plain filter, so an unknown id returns an empty page there rather than a 404. Check the id before concluding a player holds nothing.
• Every read surface keys on your id, never on a Parity uuid, so you never store a second identifier for the same person and then have to reconcile the two.
• The id is scoped to your operator. Two partners may use the same string for different people with no collision.

• A key is shown exactly once, in the response that creates it. Parity stores a SHA-256 hash and a short non-secret prefix; there is no code path that recovers a key from the database.
• The prefix (the leading characters, pk_test_XXXX or sk_live_XXXX) is what a console shows and what a log line may safely carry. It identifies which key to revoke and cannot authenticate anything.
• Revocation is a timestamp, never a delete. A revoked key returns 401 revoked_key and stays on the record.
• A suspended operator returns 403 operator_suspended on a key that is otherwise perfectly valid.
• The prefixes are kept deliberately greppable so secret scanners catch an accidentally committed key.

Every /api/v1 route names the single scope it needs and the gate checks it before the handler runs. A key that lacks it gets 403 insufficient_scope with the scope it wanted in a required field, so the fix never has to be guessed.

The table below is a summary. The complete, generated route-by-route scope list is on Rate limits, which is built from the OpenAPI document rather than typed out, so it cannot go stale.

Scope is checked before the rate limit is consumed

A caller with the wrong scope has made a mistake no amount of waiting fixes. Burning their quota to say so would turn a 403 into a 429 on the retry, which reads as a completely different bug and sends whoever is debugging it to the wrong page. The order is fixed: key, then scope, then limit, then tenant mode.

Orders are idempotent on clientOrderId, scoped to the operator and the player. The guarantee comes from a unique index on (operator, user, clientOrderId), so two requests arriving at the same instant produce one order and the loser re-reads the winner's.

POST /api/v1/orders  { "quoteId": "...", "clientOrderId": "ticket-9031" }
→ 201  { ..., "idempotentReplay": false }   first call, order created

POST /api/v1/orders  { "quoteId": "...", "clientOrderId": "ticket-9031" }
→ 200  { ..., "idempotentReplay": true }    same order returned

• Derive the key from the reservation in your own ledger (your ticket or bet id), never from a clock and never from a random value per attempt. A retry has to present the same string to be worth anything.
• A rejected order still consumes its clientOrderId. That is deliberate: retrying a spent key must not open a second live order.

Two per-minute limiters run on every /api/v1 route: one per key, and one per operator across every key it holds. Most responses, a success as much as a refusal, carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset for the key. The quote and order routes answer without them, and no header reports the tenant counter. Full semantics on Rate limits.

Your API key is a server credential and must never reach a browser. To mount Parity Embed inside your own page, exchange it server-side for a short-lived session scoped to one of your customers. This section is about the credential. The full integration (iframe, sizing, the message handshake, the reserve handshake) is on that page.

curl -X POST $PARITY_BASE/api/v1/embed-sessions \
  -H "Authorization: Bearer $PARITY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalUserId":"your-customer-id","returnOrigin":"https://your-app.example"}'

# → { "token": "pes1.…", "expiresAt": "…", "expiresInSeconds": 900, … }

Hand that token to the browser and let it mount the embed. It authorises the embedded customer experience for one operator and one customer and nothing else: not your API key, not another tenant, not another of your customers, not admin, and no venue credential.

• Needs all three scopes. markets:read, quotes:write and orders:write together. A session can browse, quote and order, so the key that mints one must be able to do all three itself. Any other rule would let a deliberately narrowed key mint a wider capability than it holds. A key missing one gets 403 insufficient_scope naming which.
• Short-lived. 15 minutes by default, 60 seconds to 1 hour by request. Mint a new one rather than trying to extend one.
• Header only. Send it as Authorization: Embed <token>. A token in a query string is refused outright, because query strings land in logs, browser history and referrer headers, and a credential that leaks that way leaks quietly.
• Origin-bound. Supply returnOrigin and the session only works from that origin. It is a browser-scoped control: it stops a leaked token being used on someone else's page, not from a terminal.
• Revocable. Because it is a handle rather than a self-describing token, a session can be ended immediately, for self-exclusion, a suspension, or a leak.

The TypeScript client takes the key once and threads the player header for you, so the two identities cannot be swapped by hand on a call.

import { ParityClient } from '@/sdk';

const parity = new ParityClient({
  baseUrl: process.env.PARITY_BASE!,
  apiKey: process.env.PARITY_KEY!,   // pk_test_… in sandbox
});

// Catalogue reads need no player.
const events = await parity.listEvents({ category: 'economy', limit: 10 });

// Anything that trades is bound to YOUR id for the player.
const player = parity.forUser('user-4471');
const quote = await player.quoteBuy({ contractId, side: 'YES', stake: '50.00' });

A missing scope surfaces as a typed InsufficientScopeError carrying required. See the SDK.

/api/demo/quotes and /api/demo/orders take no credentials. They run the same pricing and order code as the partner routes under a well-known demo operator, which is what makes the public demo evidence that the partner path works rather than a parallel implementation.

If you resell Parity to your own downstream operators, you hold ONE key and name which operator each request is for. Send x-parity-operator carrying that operator's id, alongside your usual x-parity-user. Omit it, or name your own id, and nothing changes: you are an ordinary direct tenant.

A key may act for itself, and for an operator it is the direct parent of. Nothing else. Naming an operator you do not parent is 403 operator_not_permitted, and the refusal deliberately does not tell you whether that operator exists, because an error that distinguishes "not yours" from "not real" is a way to enumerate other tenants.

Each downstream operator is a full tenant in its own right, so its market offering, wager limits, display currency, language, fees and reporting are its own and are configured the way any tenant's are. Rate limits are metered per operator rather than per key, so one busy downstream client cannot spend another's budget.