Security and data handling
The security boundaries and data-handling rules an integration must follow.
Your responsibilities
- Store API keys, webhook secrets and dedicated-storage credentials in a secret manager.
- Treat a secret shown during creation or rotation as the only copy you will receive.
- Give each integration only the scopes it needs.
- Keep organizer credentials separate and never accept a tenant id from an untrusted client.
- Verify webhook signatures against the raw body before parsing it.
- Deduplicate webhook deliveries on
webhook-id. - Keep player identifiers opaque. Do not use an email address or phone number as
playerId. - Avoid logging credentials, secrets, raw player tokens or sensitive webhook bodies.
Identity boundaries
Administrator, API-key and Player credentials serve different planes and cannot substitute for one another. Your trusted backend presents a dedicated Player-session credential and stable external Player id to Account Auth, which returns a 15-minute Player context. Other services receive the context, not the session credential or external identifier.
Keep the Player-session credential in a backend secret manager. Never put it in a browser, URL, cookie or log. See Create a Player session.
Secrets and webhooks
API keys are stored as keyed digests. Dedicated connection strings and webhook signing secrets are
encrypted at rest. Webhook rotation can temporarily sign with both the active and retiring secret,
so receivers should accept any valid v1 entry in the signature header during that window.
See Verifying signatures for the tested verification sample.
Tenant and player data
Tenant access is derived from authentication and remains scoped to the resolved accountId.
Dedicated storage fails closed rather than falling back to shared storage. See
Multi-tenancy.
Tanitar stores an opaque player id and the records needed for platform features, such as events, ledger entries and inbox items. The player's external subject and profile stay at the identity boundary. Retention and erasure requirements are agreed during onboarding.
Tracing without disclosure
Every service exposes GET /health/live, GET /health/ready and GET /meta. These endpoints carry
no tenant data. Use the requestId returned with an error when contacting support. Error responses
provide stable codes without revealing whether another tenant or resource exists.
See The governed request for access failures and Errors for response handling.