Platform Integration
How a gameserver-orchestration platform wraps the managed IVK Match service so that, to the platform’s customers, matchmaking looks and feels like a native feature of the platform: created from the platform’s console, billed on the platform’s invoice, reachable with the platform’s login.
There are four touchpoints, and they are independent — each one can ship without the others:
- Accounts and tenancy — who creates customer accounts, and how.
- Unified billing — one invoice, from the platform.
- Single sign-on — the platform’s login opens the matchmaker’s tooling.
- Provisioning integration — the matchmaker requests game servers from the platform directly.
Most of this document is planned. What works today is the base case: a customer account onboarded by Invokation, integrated over the public APIs with Model A flows. The touchpoints below are the menu for deepening that into a native platform feature, in roughly the order listed.
Accounts and tenancy
Section titled “Accounts and tenancy”Every platform customer that uses matchmaking maps to one account on the managed service. The account holds the customer’s queues, their API credentials, and their usage records. Isolation between customers is per account.
Three onboarding shapes, in increasing order of integration depth:
| Shape | How an account is created | Status |
|---|---|---|
| Referral | The customer signs up with Invokation directly; the platform points them at us. | Available today |
| Platform-managed | The platform creates and owns accounts on behalf of its customers through an account-management API: create, suspend, delete, rotate credentials. The customer may never see Invokation at all. | Planned. |
| Provisioned per deployment | Account creation hangs off the platform’s own flow — deploying a game on the platform can create the matchmaking account and its first queue in the same action. Built on the same API as platform-managed. | Planned. |
Platform-managed accounts are the shape unified billing and SSO both build on: the platform is the party of record, and the customer’s relationship with Invokation is mediated entirely through it.
What the account-management API needs to expose (all planned):
- Create / suspend / delete an account, keyed by the platform’s own customer identifier.
- Issue and rotate the account’s API keys, so the platform can hand credentials to its customer or inject them into the customer’s deployment without a manual exchange.
- Read usage per account (see billing).
- Manage queue-config documents per account, so a platform that wants to can surface queue authoring in its own console instead of ours. The document format is exactly Queue Configuration; validation and hot-reload semantics are identical.
Unified billing
Section titled “Unified billing”Platform customers strongly prefer one invoice. The model that supports that:
The platform is the billed party. Invokation bills the platform for all accounts the platform owns, at wholesale/reseller terms; the platform bills its customers however it likes — marked up, bundled into an existing plan, or given away on higher tiers. The customer never holds a payment relationship with Invokation.
What the platform needs from us to make that work (all planned):
- Usage metering per account, exposed over the account-management API: tickets created, matches formed, active queues, peak concurrent pool size — whatever the billable unit ends up being, reported per account per period, machine-readable.
- A single consolidated statement for the platform across all of its accounts, reconcilable against the per-account usage data.
- Spend controls per account: caps or alerts the platform can set so one customer’s runaway usage is the customer’s problem, not a surprise on the platform’s invoice.
The billable unit itself is a commercial decision, not fixed by these docs. The mechanics above hold for any of the candidates (per ticket, per match, per monthly active queue, per pool-size tier).
Referral-shape accounts bill the customer directly and need none of this.
Single sign-on
Section titled “Single sign-on”The managed service comes with a web console per account: queue inspection, the live pool, recent matches — the operator dashboard the self-hosted shape runs on port 3002, delivered as part of the service. Customers of a platform should not need a second set of credentials for it.
Planned. Federated login: the platform acts as an OpenID Connect identity provider, and the matchmaker console accepts its identities for the accounts that platform owns. A customer signed in to the platform’s console follows a link and lands in their matchmaking console without a second login.
Two levels, in order of effort:
- OIDC federation — “Sign in with 4Players / Edgegap” on our console for platform-owned accounts. Standard OIDC; the platform needs to expose an issuer and map its customer identifier to the account.
- Embedded console — the platform embeds our console views in its own, so the customer never leaves the platform’s console at all. Needs federation first, plus an embedding contract. Whether this is worth doing over a deep link is an open question.
SSO governs the console only. The game backend’s API access uses the account’s API keys regardless; machine credentials do not federate.
Provisioning integration
Section titled “Provisioning integration”The deepest touchpoint: the matchmaker requests game servers from the platform itself. This is Model B — a formed match triggers a provisioning call to the platform, and the outcome delivered to the game backend already carries the server address.
For an orchestration platform this is the feature that makes the pairing turn-key: a customer with no backend logic for provisioning at all can go from “player presses Play” to “player connects” with the platform and the matchmaker doing everything in between.
Planned. The flow, the failure handling, and the recommended webhook contract — where the platform implements one provisioning endpoint and keeps its own API private — are specified in Integration Flow § Model B.
What the platform brings to the table:
- A provisioning endpoint (or API access) the managed service can call, with per-account credentials.
- Host keys: the placement identifiers customers use in
Player.latenciesshould be the platform’s own region/site identifiers, sohost.preferredpasses straight into the provisioning call with no translation. Agreeing that vocabulary early pays off in both models — see Integration Flow § Step notes. - Idempotency on
match_id, so a retried provisioning call never leaks a second server. - Honest capacity errors, so the matchmaker can walk
host.acceptableand, when every host fails, return the match’s tickets to the pool.
Suggested sequence
Section titled “Suggested sequence”| Stage | What ships | What a platform customer gets |
|---|---|---|
| 1 | Managed service, referral accounts, Model A | Working matchmaking against hosted APIs; two vendor relationships |
| 2 | Account-management API + platform-managed accounts | Matchmaking enabled from the platform’s console; one vendor relationship |
| 3 | Usage metering + platform billing | One invoice |
| 4 | OIDC federation | One login |
| 5 | Provisioning integration (Model B) | Turn-key: no provisioning code in the customer’s backend |
| Later | Self-hosting license | The platform runs IVK Match inside its own infrastructure; the self-hosting documentation covers its deployment requirements. |
Stages 2–5 are ordered by expected value to the platform, but they do not depend on each other; a platform that cares most about turn-key provisioning can pull stage 5 forward.