Advanced Runtime API

Exchange a provider token for a Persistly account session.

Most games should use the SDK auth helper when one is available. This direct HTTP example is for custom engines, custom SDKs, advanced integrations, and teams validating the public runtime contract.

Advanced Request

POST /api/v1/accounts/auth/session

Use a runtime key in Authorization. The JSON body contains provider, token, and optional deviceLabel only. The account headers are optional and are used only to link a verified identity to the current account.

HTTP

POST https://api.persistly.app/api/v1/accounts/auth/session
Authorization: Bearer ps_test_your_runtime_key
X-Persistly-Account-ID: acc_01HXYZ
X-Persistly-Account-Session: pst_01HSESSION
Content-Type: application/json

{
  "provider": "firebase",
  "token": "FIREBASE_ID_TOKEN_PLACEHOLDER",
  "deviceLabel": "iPhone"
}

Advanced Response

200 OK

The response returns a normal Persistly accountId and accountSessionToken for later account and slot routes.

JAVASCRIPT

HTTP/1.1 200 OK
Content-Type: application/json

{
  "accountId": "acc_01HXYZ",
  "accountSessionToken": "pst_01HNEWSESSION",
  "isNewAccount": false,
  "linkedProvider": "firebase",
  "wasProviderNewForAccount": true
}

Plan Gate

403 auth_bridge_requires_paid_plan

Free workspaces can test Auth Bridge with Stage runtime keys. Production Auth Bridge requires a paid workspace plan before provider token verification runs.

JAVASCRIPT

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "code": "auth_bridge_requires_paid_plan",
    "message": "Production Auth Bridge requires a paid workspace plan.",
    "details": {
      "environment": "prod",
      "plan": "free",
      "upgradePath": "https://dashboard.persistly.app/settings/billing#plans"
    }
  }
}

Conflict

409 account_auth_conflict

If the provider identity is already linked to another account, Persistly returns a safe summary with counts and timestamps only.

JAVASCRIPT

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "account_auth_conflict",
    "message": "Auth identity is already linked to another account.",
    "details": {
      "summary": {
        "linkedProvider": "firebase",
        "linkedProviderCount": 1,
        "linkedAccount": {
          "activeSlotCount": 3,
          "lastActivityAt": "2026-06-06T12:30:00Z"
        },
        "firstLinkedAt": "2026-06-06T12:00:00Z",
        "lastLinkedAt": "2026-06-06T12:00:00Z",
        "lastUsedAt": "2026-06-06T12:30:00Z"
      }
    }
  }
}

Rules

Provider tokens only belong on the auth session route.

Prefer the Persistly SDK auth helpers when an SDK is available.

Use this direct API only for custom engines, custom SDKs, advanced integrations, or contract tests.

Send provider, token, and optional deviceLabel in the JSON body.

Send X-Persistly-Account-ID and X-Persistly-Account-Session headers only when linking the verified identity to a current account.

Never send accountId or accountSessionToken in the auth session JSON body.

Do not log provider tokens, provider subjects, subject hashes, or account session tokens.

Free workspaces can use Stage runtime keys for Auth Bridge testing. Production runtime keys require a paid workspace plan.