AUTH4D-364 Sign-in completion report

A paid, per-application report of hosted-login sign-ins in browser applications: how many attempts started, how players signed in, how many met and passed the verified email step (AUTH4D-262 (repository file docs/api-spec/auth4d-262.md)), and how many reached the application with tokens. It is shown on the console’s project overview and is read through the management API.

The report is the sign_in_report add-on (AUTH4D-165 (repository file docs/api-spec/auth4d-165.md)): a monthly line on an Indie or Studio plan, or a platform-operator override. PILOT: the price is R149 per project per month while it is tested with five studios, and may change before it is confirmed.

Read the report

GET /management/tenants/{tenantId}/clients/{clientId}/sign-in-report?days=30

Needs a management token with client:read and live membership of the project; every role can read it. days is optional, a whole number from 1 to 30 (default 30). The window is the last days UTC dates, ending with today.

200, with Cache-Control: no-store:

{
  "report": {
    "client_id": "cli_…",
    "from": "2026-09-27",
    "to": "2026-10-26",
    "generated_at": "2026-10-26T09:00:00.000Z",
    "deadline_minutes": 60,
    "totals": {
      "started": 120,
      "authenticated": 104,
      "email_step_required": 31,
      "email_step_verified": 22,
      "code_issued": 95,
      "completed": 93,
      "expired": 25,
      "pending": 2
    },
    "daily": [{ "date": "2026-09-27", "counts": { "started": 4, "…": 0 } }],
    "methods": [
      { "method": "steam", "counts": { "started": 40, "…": 0 } },
      { "method": null, "counts": { "started": 16, "…": 0 } }
    ]
  }
}
  • daily has one entry per date in the window, oldest first, including days with no attempts.
  • methods is sorted by started, highest first. method is a sign-in method (email, password, passkey, phone, discord, steam, epic, google, apple, microsoft, sso, game_center, session for a reused hosted session, …) or null for attempts that never got past the sign-in screen.
  • In every counts, completed + expired + pending = started.

Errors

The management error envelope ({"error": {"code", "message", "request_id"}}).

Status code When
400 validation_failed days is not 1 to 30, is repeated, or another query parameter is set
401 unauthorized No valid management token
402 feature_not_entitled The project has neither the add-on nor an override
403 forbidden The caller is not a member of the project
404 not_found The application is not in the project
429 rate_limited The per-developer management budget is spent
503 not_ready Migration 0046 is not applied yet
503 temporarily_unavailable Any other failure; safe to retry

Definitions

  • Attempt. One accepted GET /oauth/authorize for a browser application that opens hosted login (AUTH4D-12). The attempt is identified server-side by a keyed SHA-256 hash of the project, the application and the request’s PKCE code_challenge. A reloaded or retried request carries the same challenge, so it is the same attempt; so is the request the verified email step reopens when the player picks another sign-in method. An application that reuses one challenge for several attempts sees them counted as one.
  • Cohort. An attempt counts on the UTC date it started, whatever time later milestones happen. An attempt started at 23:59:59 UTC that completes after midnight counts on the earlier date.
  • Milestones. Each is counted at most once per attempt, at its first occurrence.
    • authenticated: a sign-in method identified the player at /oauth/authorize/continue, or an existing hosted session was reused. The method is the latest one used before completion.
    • email_step_required: the verified email step was shown. An attempt that never needs the step (the application’s setting, or the player already has a verified address) skips it and both email counts stay unchanged.
    • email_step_verified: the player proved an address and the request resumed.
    • code_issued: an authorization code was sent to the application’s redirect URI.
    • completed: the application redeemed that code at POST /oauth/token. Provider sign-in or code issue alone is not completion; a failed exchange (wrong verifier, wrong redirect URI, replay, suspended account) is not either.
  • Authentication deadline. 60 minutes after the start. Until then an attempt that has not completed is pending; afterwards it is expired (expired without completion). The report does not say why: the player may have closed the page, failed a code, been refused by a Flow, or the application may not have exchanged its code. Milestones after the deadline are ignored.
  • Not covered. Token refreshes, silent session restores (prompt=none, AUTH4D-140), hosted guest starts (AUTH4D-167), native and device sign-ins (AUTH4D-16), and authorization requests refused before hosted login opens (bad client, redirect URI, scope or PKCE, or the rate limit).

Storage, retention and cost

Migration 0046_sign_in_report.sql. sign_in_attempts holds one row per open attempt with the application id, the start date, the start and deadline times, the method and one time per milestone. It holds no state, challenge, code, token, flow id or cookie, email address or IP address. Every query filters on the project, and the report also on the application.

The hourly maintenance run (the first lifecycle run of each hour) folds every closed day into sign_in_daily_rollups, one row per application, day and method with the milestone counts. A day is closed at 01:00 UTC the next day, once its last attempt reached the deadline. The rollup and the delete of that day’s attempt rows are one batch, so a day is counted exactly once. Rollups are kept for 400 days; the report shows at most 30. Rows go with their application and project.

Attempts are recorded for every project, entitled or not, so the last 30 days are there as soon as the add-on is turned on. Recording never fails or changes a sign-in: each write is one primary-key statement whose errors (including a missing table) are dropped.

Per attempt D1 rows written
Started and abandoned 1
Completed without the email step 4 (start, signed in, code, completion)
Completed through the email step 6
Refresh, silent restore or device 0
Each closed day (hourly run) 1 per application, day and method used

Each write is one awaited single-row D1 statement on a primary key. Authorize and the token exchange gain one; /oauth/authorize/continue gains two (signed in, then the email step or the code) and the email step’s resume gains two (passed, then the code). The report read is two indexed queries in one batch.

Source: docs/api-spec/auth4d-364.md