# Steam linking for Hybrid Arena and other applications

Hybrid ID remains your application's identity provider. Steam is a separately verified linked account. Never replace the application's stable `(iss, sub)` key with a Steam nickname or email.

## User journey

1. Send the user to `https://hybrid-id.com/account/linked-accounts` (a new tab works well). This preserves the destination through Hybrid ID sign-in if needed.
2. In **Security & sessions → Linked accounts**, choose **Steam** and **Connect Steam**. Apple and Google appear in the same selector when configured; their existing authenticator and provider policies remain in force.
3. The user authenticates on Steam's own site and returns to Hybrid ID. Hybrid ID checks the Steam-signed OpenID 2.0 response directly with Steam, then shows the exact Steam ID for confirmation.
4. Only **Confirm link** saves the account. Cancelling does not create a link. One active Steam account per Hybrid ID; the same Steam account cannot be reassigned to a different Hybrid ID, including after disconnect. Contact support for an ownership dispute; there is no email/name-based account merge.
5. Back in your application, request `openid linked:steam` in your existing Authorization Code + PKCE S256 flow. Hybrid ID asks for the new permission; an existing valid Hybrid ID session can be reused without entering credentials again. Preserve your application's own callback state and account binding. Never force `prompt=login` merely to obtain new consent.
6. Exchange the code on your backend, validate the ID token as usual, then call the endpoint below with that token's `sub` and the new **access token**. If Steam is already connected and permission is already granted, read it directly.

The linking page does not accept arbitrary return URLs or call application callbacks. After linking, the user returns to the application's tab. Applications may provide a **I've connected Steam — continue** button that begins the consent/read step. A new app token is needed if the old token lacks `linked:steam`; requesting a permission never silently grants it.

## Server-side read contract

### Supported Node.js helpers

Download the [OIDC helper](https://hybrid-id.com/integrations/hybrid-id-node.mjs)
and [Steam reader](https://hybrid-id.com/integrations/hybrid-id-steam.mjs) into your
server application. The OIDC helper uses `openid-client` 6.8.8 on Node 22+.
For a user already signed into your app, request additional Steam consent with:

```js
const {url, transaction} = await beginSignIn(config, registeredCallback, {
  linkedSteam: true,
  expectedSubject: currentAppSession.subject,
});
// Save transaction server-side, bound to this browser and its current app session.
// Atomically consume it at callback, then:
const identity = await finishSignIn(config, callbackUrl, savedTransaction);
// Recheck the app session is still the account that initiated this transaction.
const steam = await readSteamLink({
  clientId, clientSecret,
  subject: identity.subject,
  accessToken: identity.accessToken,
});
```

`expectedSubject` must come from your authenticated server session, never a form
field. It rejects consent from a different Hybrid ID account before any UserInfo
read. `linkedSteam: true` requests the scope and retains the access token in the
server-only callback result; it does not guarantee permission was granted.
Ordinary sign-in keeps its existing scopes and result shape. Never serialize
either helper's token-bearing sign-in result into a browser response.

The Steam reader pins the endpoint, rejects redirects, limits response size/time,
and validates issuer, client, subject, field shapes and snapshot freshness. It
returns `linked` or `not_linked`, or throws `SteamLinkError` with `code`, `status`
and optional `retryAfter` seconds. It creates no roster, service, or identity
cache. Refresh stale evidence for admission decisions; never infer a missing
link from an outage. Refer to the response/error contract below.

### HTTP operation

`POST https://auth.hybrid-id.com/accounts/steam`

- HTTP Basic: the registered `client_id` and current `client_secret` (server only).
- `Content-Type: application/json`. Browser-origin requests are rejected; no CORS access.
- JSON: exactly `subject` (validated ID-token subject) and `access_token` (OIDC access token issued to the same application with `openid linked:steam`).
- Requires a current token, grant, native session and saved user consent. App disable, secret rotation and consent withdrawal are checked on every read, including after the native lookup.

```js
const response = await fetch('https://auth.hybrid-id.com/accounts/steam', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + Buffer.from(`${clientId}:${clientSecret}`).toString('base64'),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({subject: validatedIdToken.sub, access_token: tokens.access_token}),
  cache: 'no-store'
});
// Handle non-2xx before reading a successful account response.
```

```json
{
  "schema": "hybrid.linked-steam.v1",
  "issuer": "https://auth.hybrid-id.com",
  "client_id": "YOUR_CLIENT_ID",
  "subject": "APP_PAIRWISE_SUBJECT",
  "state": "linked",
  "steam_id": "76561198000000000",
  "linked_at": "2026-10-07T00:00:00Z",
  "observed_at": 1791331200,
  "valid_until": 1791331260
}
```

Keep `steam_id` as a **string**; JavaScript numbers cannot safely represent SteamID64. An authoritative missing/disconnected link returns HTTP 200 with `state: "not_linked"` and **no** `steam_id` or `linked_at`. No native identity UUID, session credential, email or other account links are returned.

## Consent, refresh and removal

`linked:steam` allows private account matching and gaming features within the requesting application. It does not grant public redistribution, Steam login as a Hybrid authentication factor, KYC, avatars, game/library ownership, inventory, purchases or achievements. Separate Steamworks contracts are required for those capabilities. Basic sign-in does not disclose the Steam ID.

Responses use `Cache-Control: private, no-store`. Refresh when displaying or acting on the link; snapshots are valid for at most 60 seconds and never beyond current consent expiry. Do not use a stored Steam ID as a fresh proof of control. After `not_linked` or `access_denied`, stop using and remove the synchronized Steam association. Revoke access also stops further disclosure; already received copies cannot be remotely erased. Keep unrelated app-owned gameplay records under `(iss, sub)`.

An outage is **not deletion**: mark the association unavailable and retry; do not issue new Steam-dependent access using stale evidence. Scope consent authorizes use, not indefinite retention or public posting. Store per `(issuer, client_id, subject)`; never cache one user's result for another.

| Status | Error | Action |
| --- | --- | --- |
| 400 | `invalid_request` | Correct JSON, method/path usage or unsupported fields. |
| 401 | `invalid_client` | Check app credentials, rotation and active registration. |
| 403 | `access_denied` | Stop using the association. Obtain a valid session/token and explicit consent if the user chooses. |
| 405 | `method_not_allowed` | Use POST. |
| 413 | `request_too_large` | Request must be at most 8 KiB. |
| 429 | `rate_limited` | Respect Retry-After (60 seconds). Standard allowance: 120 reads per app/subject/minute; existing owner exemptions remain. |
| 503 | `temporarily_unavailable` | Retry later; do not interpret as disconnected or verified. |

## Acceptance and availability

See deployment evidence (contact the integration team) for the exact revision and validation boundary. Automated tests cover forged assertions, callback/session binding, replay, app/subject isolation, conflicts, update/unlink and consent withdrawal. Steam's actual user authentication requires an account holder to complete the live ceremony; synthetic fixtures are not evidence of a real Steam-account acceptance test.

Discover this contract in the [integration manifest](https://hybrid-id.com/integrations/manifest.json) and [OpenAPI](https://hybrid-id.com/integrations/linked-accounts.openapi.json).

## Optional public link verification

Private `linked:steam` consent never publishes a Steam ID or a receipt. Separately,
an owner can choose **Publish link receipt** in Hybrid-ID → Linked accounts,
confirm public disclosure, and complete the existing authenticator step-up.
The resulting link opens Hybrid Explorer's Identities → Linked-account receipts.

The Ed25519-signed `HYBRID_EXTERNAL_LINK_V1` receipt contains the provider name,
a random publication ID, a randomized opaque link commitment, and a seven-day
expiry. No Steam ID, email, internal identity UUID, or provider subject hash is
published. Explorer checks the canonical issuer signature and a fresh signed
`HYBRID_EXTERNAL_LINK_STATUS_V1` response. Withdrawal or Steam disconnection
makes the receipt inactive; reconnecting does not revive an old publication.

This is an issuer attestation, not a zero-knowledge proof, game entitlement,
KYC result, or proof that the person sharing a receipt controls that account.
Saved copies cannot be erased, so verifiers must refresh live status. The receipt
is not automatically attached to an Arena profile and cannot identify a player
for roster admission; that requires the separate private consented Steam reader.
