> For the complete documentation index, see [llms.txt](https://sdk.metamarket.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sdk.metamarket.tech/architecture-and-trust/users-and-actors.md). # Roles and Permissions MetaMarket has two kinds of actors: the ones the platform authenticates and serves at runtime (Player, Device, App), and the ones who build and operate the platform without ever appearing in a JWT (System operator, Content designer, Integrating engineer). For how the archetypes below map to what your game owns versus what MetaMarket operates, see [Studio and Platform Responsibilities](/architecture-and-trust/responsibilities-and-boundaries.md). **Runtime actors:** [Player](#player) (the durable identity) · [Device](#device) (how a player proves it) · [App and tenant](#app-and-tenant) (a registered game, and its trust archetype). **Operator roles:** [System operator](#system-operator) · [Content designer](#content-designer) · [Integrating engineer](#integrating-engineer). ## Player A Player is a durable, cross-app human identity: the record a person's progress attaches to as they move between games and devices. It carries no per-app state itself, because per-app data is always addressed as the pair `(player_id, app_id)`. What matters for permissions is that a Player is never the thing that authenticates. A person proves who they are through a Device, and the only credential provider implemented today is a guest bootstrap, so passkey and social sign-in are planned rather than available. [Players and Identity](/core-concepts/players-and-identity.md) explains why one person can hold several guest Players before they link their installs, which is the part that most often surprises an integrator. ## Device A Device is a player's access point, not their identity. It holds a private key the server never sees, and signing in means proving possession of that key rather than presenting a password. A bare device id is never enough to obtain a session for a device the platform already knows. Two consequences shape how you model users: * A phone keeps each app's credentials separate, so one person playing two of your games on one handset is two devices to the platform. Only a one-time handoff code unites them under a single Player. * Unbinding a device revokes its refresh token. It cannot sign in again, and its access ends when the current access token expires. [Authentication](/evaluate-and-integrate/authentication.md) has the signing scheme, refresh rotation, and the handoff and unbind calls. ## App and tenant An App (also called a tenant) is a registered game or platform module: a row in the platform's app registry with an id, a secret, a status (which acts as a kill switch), and a JSON configuration describing which actions and mechanics it's allowed to run. Every piece of tenant data in the system carries and is scoped by this app id. For an external game, the app id a request can act as is fixed server-side by the edge gateway it is provisioned for, which rejects any other, so an external integration operates only within its own app id's data; multi-tenant access from one process is the internal first-party path only. Every app is assigned exactly one of three trust archetypes at registration. The archetype decides which entry path (door) an app's clients use and what that app is allowed to touch, independent of what the app's game content actually looks like. | Archetype | Trust | What it can design/touch | Cannot | | ---------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | **external** | Untrusted third party | Own local actions, local resources with regen, local currencies, local quests with local rewards | Write platform gold/gems directly, own platform-level quests, read another app's data, read the platform currency balance | | **friend\_of\_system** | First-party platform module (for example a shop or achievements module) | Everything `external` can, plus reading the platform currency balance and running reward packages that grant or spend it | Still cannot define platform-level quests or manage other apps | | **system** | The platform itself (singleton) | Owns all global resources, the app registry, and platform/bridge quests that observe activity across every app | Not something a content designer configures (run by platform architects) | An `external` app's only route to platform currency is passive: it satisfies conditions that a platform-owned bridge quest observes, and the platform decides what that's worth. It can never mint or move platform currency itself. For the object-by-object breakdown of what a connected game can read and change, see the access table in [Local and Shared Economies](/core-concepts/shared-economy.md#what-a-connected-game-can-touch); for how the archetype boundary is enforced, see [Studio and Platform Responsibilities](/architecture-and-trust/responsibilities-and-boundaries.md). Archetype also decides the door a client uses: `external` clients must go through the edge gateway and cannot reach the `system` app at all; `system` and `friend_of_system` clients talk to the game engine directly. ## System operator The System operator is the platform itself, running as the `system`-archetype app. It is a privileged tenant: it owns the shared balance, the app registry, and the platform/bridge quests that pull value in from other apps, but architecturally it is still just one app among others, addressed the same way any app is. In practice this actor is operated by the platform's own architects, not configured by game designers. ## Content designer A content designer authors the configuration that defines a game's actions, resources, reward packages, quests, and pool content. It is a human role rather than an authenticated principal. New content (a new quest chain, a new shop item, a new resource with its own decay curve) is added by writing config, not by changing platform code. The one thing a content designer working on an `external` app cannot do is reach past their own app's local economy into platform-owned resources or quests. That boundary is enforced by the archetype. (Turning a plain-language description into working configuration automatically is a Future direction on the [Roadmap](/releases-and-reference/roadmap.md), not a current capability.) ## Integrating engineer An integrating engineer is the developer integrating a game or platform module with MetaMarket. Which SDK they use follows directly from the app's archetype and door: * An engineer building an **external** game uses the narrow client SDK. It embeds the app's id once at startup and stamps it on every request automatically. An external developer never has to manage app context because they only ever have the one game. * An engineer building a **first-party module** (`system` or `friend_of_system`) uses the wide platform SDK. This is an internal-only path: the `system` app, `Platform.Sdk`, and the privileged surfaces they reach are operated by MetaMarket and are not part of an external partner integration (see [Product availability](/overview/current-scope.md)). It takes an app id per call so one client (the Meta App) can address many tenants from a single session without mutating shared state per request. Both SDKs are built on the same client core.