Authentication
Every call a game backend makes to an Invokation API is authenticated with credentials issued to that game. Credentials are created, rotated, and revoked in the portal.
Calls come from the backend, never the client
Section titled “Calls come from the backend, never the client”The API is a backend-to-backend surface. The game client talks to the game backend; the game backend talks to Invokation.
Secrets are only part of the reason. The game backend is where authentication, anti-cheat, skill lookup, and rate limiting already live, and it is the boundary that allows matchmaking behaviour to change without shipping a client build. A credential embedded in a game client can be extracted from it, and whoever extracts it can act on the game’s queues.
Keep credentials in the same secret store as the backend’s other secrets, and load them the same way. They do not belong in queue configuration, in source control, or in a game client.
Attaching credentials
Section titled “Attaching credentials”Credentials are bearer tokens, carried in an Authorization header on every request.
Both transports work the same way, and both require TLS.
Authorization: Bearer <token>Over gRPC that is call metadata; over HTTP/JSON it is an ordinary request header. The header name and format are identical either way.
A token issued in the portal is shown once. Store it at that point; it cannot be retrieved again, only replaced.
Endpoints
Section titled “Endpoints”| Service | Endpoint |
|---|---|
| IVK Match | match.ivk.dev |
TLS is terminated at the endpoint, so use https:// for HTTP/JSON and a TLS channel for
gRPC. Plaintext connections are rejected.
Rotation
Section titled “Rotation”Credentials can be rotated without downtime: issue the new one, deploy it, then revoke the old one. Because a credential authenticates a game rather than a single queue, rotating it affects every queue on that game at once, so make the overlap window long enough to cover a full deploy.
Losing a credential
Section titled “Losing a credential”Revoke it in the portal. Revocation takes effect immediately and any backend still presenting the old credential starts failing authentication, so deploy the replacement first where possible.