2. Generate a Ticket

A ticket is a short-lived credential that authorizes one player to open one WebSocket connection. Your backend requests a ticket on behalf of a player right before that player is about to connect — not ahead of time, and not once per session to be reused.

Pairiquium is globally hosted

Matchmaking runs in multiple regions — currently eu-west-2 (Europe) and us-east-1 (US East) — rather than one central location. By default, this endpoint automatically detects the region closest to whichever of your backend's servers calls it and mints a ticket for that region, so you don't need to do anything to get a low-latency connection for most players. If your own backend runs somewhere that doesn't reflect where the player actually is (e.g. a single backend region serving a global player base), pass preferredRegion to pick explicitly instead — see below.

Request

POST https://api.pairiquium.com/v1/tickets
X-MaaS-API-Key: mk_live_...
Content-Type: application/json
 
{
  "userId": "player-123",
  "attrs": {
    "mmr": 1500
  },
  "preferredRegion": "us-east-1"
}

Field	Required	Notes
`userId`	Yes	Your own identifier for the player.
`attrs.mmr`	No	Integer, `0`–`10000`. Required if the player will queue for an MMR-based game mode.
`preferredRegion`	No	`eu-west-2` or `us-east-1`. Overrides automatic region detection — use this if you already know which region is best for this player (e.g. from their own location) rather than your backend's.

Response

{
  "ticket": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "wsEndpoint": "wss://ws.eu-west-2.pairiquium.com"
}

wsEndpoint is the WebSocket URL for the region this ticket was minted for — always use the value from the response rather than hardcoding one, since it changes depending on which region served this particular ticket (automatically or via preferredRegion). The ticket is locked to this region: it will be rejected if presented to any other region's WebSocket URL.

Parties need a shared region

Parties live in a single region, so every member of a party must hold a ticket for the same region. If players you expect to group up can be served by different regions, pass the same preferredRegion when generating their tickets.

Hand both values straight to the game client — wsEndpoint is the URL to connect to, and ticket is what gets passed to it, in the next step.

Properties of a ticket

Expires in 5 minutes. Request it just before the client is ready to connect.
Single-use. Once a ticket has been used to open a connection, it cannot be used again — a reused ticket is rejected. If a connection attempt fails, request a fresh ticket rather than retrying the same one.
Region-locked. A ticket is only valid against the wsEndpoint region it was minted for.

Possible responses

Status	Meaning
`200`	Ticket created — `{ "ticket": "...", "wsEndpoint": "..." }`.
`400`	The request body is missing or invalid — check `userId` is present, `attrs` values are in range, and `preferredRegion` (if given) is a currently supported region.
`401`	No `X-MaaS-API-Key` header was sent.
`403`	The API key isn't valid, doesn't have the `tickets:create` scope, or the tenant's account is on the signup waitlist.
`500`	Something went wrong on our end — safe to retry.

This endpoint is also available as an OpenAPI spec; see API Specs.

Never expose your API key to players

The API key used here authenticates your backend, not a player. If it ends up somewhere a player can read it — bundled into the game client, a launcher, or a public repo — anyone holding it can call this endpoint directly and mint unlimited tickets, running up searches and matches against your account's limits. If a key is ever exposed, rotate it immediately from the Config page in the dashboard and update your backend with the new value.