Purpose

The tournament management API lets a partner register an app, request scoped access from an account owner, exchange a single-use authorization code for a bearer token, synchronize player lists, teams, tables, and matches by external ID, inspect its assigned table queues, and receive signed score webhooks without changing existing scoring URLs or canonical Realtime Database records.

How to create it

1. 1Register an application with redirect URIs, allowed scopes, and an optional webhook URL.
2. 2Approve the request from a signed-in owner account after checking the app identity and requested scopes.
3. 3Use PKCE S256 on new authorization requests to bind the short-lived approval code to the initiating tournament-software session.
4. 4Exchange the returned authorization code for a scoped bearer token and use it on the versioned API surface.
5. 5Store the rotating refresh token and replace it atomically after every successful token refresh so owner consent does not need to be repeated.
6. 6Inspect the connection after exchange so the partner can store its stable connection ID, scopes, and token expiry.
7. 7Synchronize player lists, teams, tables, and matches with stable external IDs so retries stay idempotent.
8. 8Use incremental roster patches for day-of-event additions and withdrawals; full PUT synchronization remains available for complete snapshots.
9. 9Patch list or team metadata without resending the roster when a display name, description, jersey color, or logo changes.
10. 10Assign synchronized player lists to scoring tables, and explicitly clear links when an event ends.
11. 11Prepare up to 100 tables in one bulk assignment request and retry only the per-table failures returned with HTTP 207.
12. 12Publish scheduling rounds in batches of up to 100 matches; request order is preserved within each table queue, and only per-match failures need retrying.
13. 13Read the participants object on match responses to reconcile all singles or doubles slots back to the partner's stable player external IDs.
14. 14Move or cancel pending match assignments in batches when a tournament round changes tables or is withdrawn.
15. 15Use optional cursor pagination when reading large player-list, team, table, match, or webhook-delivery collections.
16. 16Record the OpenScoreboard-Request-ID returned by every API response, or supply a safe request ID, so partner logs can be matched to the owner's private connection activity.
17. 17Subscribe to match started, live score, completion, and corrected-result events as needed; verify signatures and use event timestamps to reconcile delivery order.
18. 18Send a persisted test webhook before match day to verify the destination and signing-secret implementation.
19. 19Inspect a delivery by event ID to compare its exact persisted payload and status before manually replaying a failed callback.
20. 20Rotate a connection's webhook signing secret when credentials are exposed or as part of scheduled key maintenance; API clients should retry a timed-out rotation with the same Idempotency-Key.
21. 21Use the connection debugger to send a safe test event, inspect delivery failures, correlate request IDs, and retry persisted webhook events before match day.
22. 22Use the Integrations dashboard to edit app settings, rotate credentials, review delivery history, retry failed webhooks, or deactivate an app.
23. 23Administrators can review endpoint and error analytics, adjust connection quotas, monitor background processing health, and export a CSV audit report.

Use it for

• Connecting tournament software that already owns draws, standings, and assignment decisions.
• Keeping native scoring and queue behavior while syncing first-party tournament metadata from another system.
• Receiving completion notifications when a table or scorekeeper finishes a match.

Notes

• Keep external IDs stable across retries and replays.
• Incremental upserts replace the mapped player's supported fields, while removals cannot delete manually managed OpenScoreboard players.
• Do not rely on private integration data being visible through client Firebase reads.
• A refresh token is single-use and remains limited to the scopes the account owner originally approved.
• PKCE is optional for backward compatibility and does not replace the registered client secret in the current confidential-client flow.
• Read the rate-limit response headers and honor Retry-After on HTTP 429 instead of retrying immediately.
• Treat a connection activity request ID as an accepted authenticated attempt, not proof that later resource validation or execution succeeded.
• Treat webhook deliveries as at-least-once and dedupe by event identity.
• Apply match.result_updated after completion when an operator corrects a finished score; unchanged result saves do not emit it.
• Webhook signing-secret rotation is immediate, and queued retries use the replacement secret, so coordinate the receiver update before resuming deliveries.
• Rotating a client secret preserves issued bearer tokens; deactivating an app revokes its connections without deleting synchronized event data.
• Configure the private webhook retry worker secret and invoke the internal retry endpoint from trusted scheduling infrastructure.
• Configure the consolidated maintenance worker secret and schedule the maintenance endpoint so webhook retries, stale queue recovery, scheduled tasks, and health snapshots continue without an open browser.
• Use connection activity to review accepted writes; request bodies and player data are not stored in the audit trail.
• Partner software can disconnect its own approved installation; owners can always revoke it independently from Integrations.