Platform Integration

How a gameserver-orchestration platform offers the managed IVK Match service to its own customers: enabled from the platform’s console, billed on the platform’s invoice, reachable with the platform’s login.

This is a co-branded arrangement, not a white-label one. The platform owns the commercial relationship and the entry point; Invokation stays named as the matchmaking provider in the portal, the documentation, and the customer-facing surfaces. We do not offer a rebranded build.

There are four touchpoints. They are independent, so each one can ship without the others:

• Organisations and tenancy: who creates customer organisations, and how.
• Single sign-on: the platform’s login opens the Invokation portal.
• Unified billing: one invoice, from the platform.
• Server provisioning: the matchmaker requests game servers from the platform directly.

Most of this document is planned. What works today is the base case: a customer onboarded by Invokation, integrating over the public APIs and provisioning its own game servers. The touchpoints below are the menu for deepening that into a native platform feature, in roughly the order listed.

---

Organisations and tenancy

Tenancy in the Invokation portal has two levels, and platform integration maps onto both:

• An organisation is the ownership and billing boundary. It holds the team members who can sign in, the billing relationship, and one or more games.
• A game (or app) holds the queues, the API credentials, and the usage records for one title. Isolation is per game.

A platform customer becomes an organisation. The games inside it are that customer’s titles.

Two onboarding shapes:

Shape	How the organisation is created	Status
Referral	The customer signs up with Invokation directly; the platform points them at us.	Available today
Platform-managed	The platform creates the organisation on behalf of its customer and remains its owner: create, suspend, delete, manage membership. The customer then adds its games inside that organisation and configures them in the portal.	Planned

Platform-managed organisations are the shape SSO and unified billing both build on: the platform is the party of record, and the customer reaches Invokation through it rather than alongside it.

What the organisation-management API needs to expose (all planned):

• Create / suspend / delete an organisation, keyed by the platform’s own customer identifier.
• Manage membership, so the platform can grant and revoke its users’ access without a manual exchange.
• Read usage for the organisation and its games (see billing).

Note what is not on that list: creating games, authoring queues, and issuing credentials are things the customer does in the portal. A platform does not have to rebuild queue management to offer matchmaking, and in the first version it should not try. Platforms that do want to drive those operations themselves have a deeper option.

---

Single sign-on

The managed service comes with the Invokation portal: queue configuration, queue inspection, the live pool, recent matches. It is the tooling a customer actually administers matchmaking with. Customers of a platform should not need a second set of credentials to reach it.

Coming soon

Federated login: the platform acts as an OpenID Connect identity provider, and the portal accepts its identities for the organisations that platform owns. A customer signed in to the platform’s console follows a link and lands in the Invokation portal without a second login.

Paired with platform-managed organisations, this is the expected first shape of a real integration, and the one we would build first. The platform creates and owns the organisation; the customer clicks through from the platform’s console and configures queues in our portal. The platform ships a link and an OIDC issuer, not a management UI.

Two levels, in order of effort:

1. OIDC federation. A “sign in with the platform” option on our portal for platform-owned organisations. Standard OIDC; the platform needs to expose an issuer and map its customer identifier to the organisation.
2. Embedded portal. The platform embeds portal views in its own console, so the customer never leaves the platform’s console at all. Needs federation first, plus an embedding contract. Whether that beats a deep link is still an open question.

SSO governs portal access only. A game backend’s API access uses the game’s API credentials regardless; machine credentials do not federate.

Driving configuration from the platform

For platforms that eventually want matchmaking configuration inside their own console rather than a link out to ours, the management API can expose the rest of the surface: create games within an organisation, issue and rotate credentials, and read and write queue-config documents. The document format is exactly Queue Configuration; validation and hot-reload semantics are identical.

This is the advanced case, not the starting point. It is worth building only once a platform has enough customers on matchmaking to justify maintaining a second configuration UI.

---

Unified billing

Platform customers strongly prefer one invoice.

The platform is the billed party. Invokation bills the platform for all organisations the platform owns, at wholesale/reseller terms; the platform bills its customers however it likes, whether 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, exposed over the management API: tickets created, matches formed, active queues, peak concurrent pool size. Whatever the billable unit ends up being, reported per game and per organisation per period, machine-readable.
• A single consolidated statement for the platform across all of its organisations, reconcilable against the per-organisation usage data.
• Spend controls: 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 organisations bill the customer directly and need none of this.

---

Server provisioning

This is the deepest touchpoint. The matchmaker requests game servers from the platform itself: a formed match triggers a provisioning call, and the outcome delivered to the game backend already carries the server address.

Coming soon

Requires a provisioning driver inside IVK Match. The design below is settled; the exact message shapes are provisional.

For an orchestration platform this is the feature that makes the pairing turn-key: a customer with no provisioning logic in their backend at all can go from “player presses Play” to “player connects” with the platform and the matchmaker doing everything in between.

The flow

sequenceDiagram
    autonumber
    actor P as Player
    participant GB as Game Backend
    participant IM as IVK Match
    participant OR as Orchestrator
    participant GS as Game Server

    P->>GB: queue_matchmaking(...)
    GB->>IM: CreateTicket(...)
    IM-->>GB: ticket_id
    GB-->>P: queued

    IM->>IM: match formed
    IM->>OR: CreateGameServer(host = preferred, match_id)
    OR->>GS: start
    GS-->>OR: ready
    OR-->>IM: server { address, port }

    IM->>GB: outcome: match.created<br/>{ match_id, tickets, teams, server{address,port} }
    GB-->>P: game_found { address, port, team }
    P->>GS: connect

Compare with backend-driven provisioning, where the game backend receives the match and calls the orchestrator itself.

What this buys

• One fewer round trip and one fewer failure surface in customer code.
• Provisioning failures are retried and compensated inside IVK Match, which already owns the pool. Returning tickets to the pool becomes an internal operation instead of a contract every customer has to implement correctly.
• The platform expresses placement policy (capacity, cost, region affinity) once, in the matchmaker’s provisioning configuration, instead of relying on every customer’s backend to get it right.
• It removes provisioning from the list of things a customer’s backend has to do. It does not on its own make a backend-less integration possible: that also needs first-party identity (Steam, PSN, Xbox) and somewhere trustworthy to keep skill ratings and other matchmaking inputs, so they come from something other than the client. Provisioning is one prerequisite of several.

One contract, not one driver per platform

IVK Match does not speak any particular orchestrator’s API, and we do not plan to ship a driver per platform. There is one provisioning contract; a platform implements an adapter on its side that translates between that contract and its own orchestrator.

The contract is transport-agnostic. The payload and the semantics are fixed; how it travels is negotiable, and we expect to offer more than one option (HTTP request/response first, with gRPC and a persistent WebSocket channel as candidates for platforms that would rather not expose a public inbound endpoint).

The HTTP shape, as an illustration of the payload:

POST <PROVISION_WEBHOOK_URL>
{
  "match_id": "…",
  "queue_id": "acme.quickplay",
  "ruleset_id": "5v5",
  "preferred_host": "eu-central",
  "acceptable_hosts": ["eu-central", "eu-west"],
  "player_count": 10,
  "teams": [ { "id": "a", "player_ids": ["…"] }, … ]
}
→ 200 { "address": "1.2.3.4", "port": 27015, "host": "eu-central" }
→ 503 { "error": "no_capacity" }        // IVK Match tries the next acceptable host

This keeps the orchestrator’s API private to the platform, and IVK Match ships one integration rather than one per orchestrator.

What the platform brings

• An implementation of the provisioning contract on one of the supported transports, with per-tenant credentials.
• Host keys: the placement identifiers customers use in Player.latencies should be the platform’s own region or site identifiers, so host.preferred passes straight into the provisioning call with no translation. Agreeing that vocabulary early pays off either way; 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.acceptable and, when every host fails, return the match’s tickets to the pool.

What it requires on our side

• A provisioning driver implementing the contract above: one driver, plus a transport implementation per supported transport, not one per platform.
• Credential management per tenant, and a place to configure the provisioning endpoint.
• A rollback path: when provisioning fails on every acceptable host, the match is abandoned and its tickets returned to the pool, with the attempt bounded by a timeout so a slow orchestrator cannot stall the queue.
• An extension to the Match message carrying the server address. It should be engine-agnostic: on Match rather than inside engine_output.

---

Suggested sequence

Stage	What ships	What a platform customer gets
1	Managed service, referral onboarding	Working matchmaking against hosted APIs; two vendor relationships
2	Organisation-management API + OIDC federation	Matchmaking enabled from the platform’s console, configured in the Invokation portal with the platform’s login; one vendor relationship
3	Usage metering + platform billing	One invoice
4	Server provisioning	No provisioning code in the customer’s backend
Later	Full configuration API	The platform surfaces queue and credential management in its own console
Later	Self-hosting license	The platform runs IVK Match inside its own infrastructure; the self-hosting documentation covers its deployment requirements.

Stages 2 to 4 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 4 forward.