Concepts
Accounts, organizers, players, administrators, Tanitar operators, and the namespaces each of them can reach.
Account (tenant)
Every organizer is an account, also called a tenant, identified by an accountId. Everything you
own on the platform is scoped to it: players, tournaments, missions, currencies, the ledger, shop
listings, API keys, Player-session credentials and webhook endpoints.
An account has:
- a plan, which carries entitlements (for example whether you may use dedicated storage) and the numeric limits that rate limiting enforces;
- an access status, which Tanitar checks on every request;
- API keys with capability scopes;
- an organization mapping that lets your administrators sign in to the dashboard;
- Player-session credentials for trusted backend assertion and webhook endpoints;
- optionally, a dedicated database if your plan entitles you to one. See Multi-tenancy.
Your accountId always comes from the credential you authenticate with. It is never read from a
request body, so one tenant can never address another tenant's data.
Organizer
The organizer is you: the organization that owns the account and offers the programme to its players. See Who it is for.
Player
A player is one of your end users. A player is not a Tanitar account: they have no Tanitar password, cannot reset anything, and sign in only with you.
After authenticating a player, your trusted backend asserts its stable external identifier with a dedicated Player-session credential. Tanitar idempotently resolves or creates the tenant-scoped Player and returns a Player context: a signed token, valid for 15 minutes, carrying only the account and Player identity. It is the only Player identity downstream services see. See Player identity.
Administrator
An administrator is a person on your team who uses the Tanitar dashboard. Administrators sign in with your organization account and act only on your tenant. See Signing in.
Tanitar operator
A Tanitar operator is a member of Tanitar's own platform staff. Operators have a separate administrative identity, reach tenants only through their own namespace, and every action they take is attributed and audited. You never call their namespace.
Namespaces (planes)
Every route is mounted in one namespace, and every governed route declares which kinds of principal it accepts. A player context is never accepted as an API key, an API key never opens the player plane, and a request that cannot be matched to an accepted principal is refused: it never falls back to an anonymous or default identity.
| Namespace | Plane | Principal | How it authenticates | Who uses it |
|---|---|---|---|---|
/v1 | Public API | Your integration | An API key carrying capability scopes, within your plan's entitlements | Your back-end systems |
/dashboard/v1 | Dashboard | An administrator | An organization sign-in session | The Tanitar dashboard, on your administrators' behalf |
/player/v1 | Player | One player | A 15-minute Player token created by your trusted backend | Your client |
A few route families sit outside these prefixes but follow the same rules. Tournament routes such as
POST /tournaments and dead-letter recovery routes such as GET /platform/recovery/dead-letters
accept API keys like any /v1 route.
Private operator and service-to-service surfaces are not part of the customer integration contract and are intentionally omitted from this documentation.
Operational endpoints (GET /health/live,
GET /health/ready, GET /meta) are public and carry no tenant data.
Scopes and entitlements
An API key carries scopes: capabilities such as rewards:read or tournaments:mutate. Each
governed route declares the scopes it needs. A request succeeds only if the key carries the scope
and your plan entitles the account to it. See
API keys and scopes.
Tenant-owned registries
Many vocabularies belong to you rather than to Tanitar: your currencies, award kinds, membership tiers, chest designs and shop listings. You extend them without waiting for a Tanitar release, next to a small fixed set of platform values. Tanitar refuses what it cannot honour. For example, an award kind you define yourself is never minted on chain.