> ## Documentation Index > Fetch the complete documentation index at: https://docs.getpioneer.dev/llms.txt > Use this file to discover all available pages before exploring further. # Identity, authentication, and authorization > How Pioneer identifies people, devices, sessions, workspaces, and agent executions, and how the gateway enforces access. Pioneer treats identity and access as gateway-owned state. A client does not decide what a role can do and does not carry a permanent gateway-wide token. The gateway authenticates a device session, evaluates the principal's current access, and compiles the capabilities that a client may present. This page covers the implementation boundary. For the client workflow, see [Account and collaboration](https://docs.getpioneer.dev/desktop/account-and-collaboration.md). For wire types and method names, see [Authentication and access API](https://docs.getpioneer.dev/protocol/auth.md). ## Identity vocabulary These records have different lifetimes and responsibilities: | Record | Meaning | Typical lifetime | | - | - | - | | Gateway | The Pioneer service a client connects to. It has a stable gateway id. | Gateway lifetime | | Principal | A person or service identity that owns access. Current principal kinds are `superuser` and `user`. | Account lifetime | | Device | One installed client, identified by an installation id and client kind. | Installation lifetime | | Session | An authenticated login of a device. It has access and refresh credentials and can be revoked independently. | Login lifetime | | Agent identity | A named non-human execution identity used for attribution and delegation. | Agent identity lifetime | | Agent execution | One concrete run performed under an agent identity. | Execution lifetime | The gateway, principal, device, and session snapshots returned by `auth/me` are separate objects. A client should keep their ids separate even when the UI shows them together. ## Device activation Device activation replaces the old shared superuser-token flow. The normal flow is: 1. An already authorized operator runs `pioneer device create` on the gateway host. 2. The gateway creates a pending device and session and returns a one-time activation code. 3. The desktop or mobile client sends its installation descriptor and the code through the restricted activation transport. 4. The gateway verifies the gateway id, consumes the pending activation, and returns an authenticated session grant. 5. The client stores the refresh credential before switching the active connection to the new access credential. The code uses eight symbols from a Crockford-style alphabet. It expires after 600 seconds by default and the gateway permits at most five failed activation attempts. The activation response contains the gateway, principal, device, and session snapshots as well as the access and refresh credentials. Activation can be represented by a `pioneer://activate` URI. The gateway base URL and gateway id are query parameters; the activation code is kept in the URI fragment. A development app scheme can be configured for non-production builds. Clients must verify the gateway id from the URI against the gateway returned during the exchange. The activation endpoint is deliberately not an ordinary authorized JSON-RPC method. `auth/device/activate`, `auth/refresh`, `invite/preview`, and `invite/accept` are accepted only by the pre-authenticated credential exchange transport. ## Session lifecycle Access credentials are short lived. The default access lifetime is 15 minutes. Refresh credentials live for 90 days by default and are rotated with a durable refresh request id. The access credential is an internal JWT representation, but clients use the session API and never need to mint or sign one themselves. Sessions have their own status and revocation reason. A user can log out the current session, revoke another session, or lose all sessions when the principal is suspended or removed. Refresh-token reuse and excessive activation failures also terminate the affected session. Session revocation is delivered to active clients through `auth/session_revoked`. A client should close the connection, discard unusable access state, and return to activation or refresh recovery. `auth/access_expiring` lets a client refresh before the access credential expires. The gateway redacts credentials in debug output and protocol snapshots. Raw access and refresh values should stay in the platform keystore on a client. Desktop gateway registry records contain credential references rather than raw values. See [Secret storage](https://docs.getpioneer.dev/architecture/secrets.md) for the gateway and client storage boundary. ## Capability snapshots Authorization is evaluated at the gateway and projected to clients through `authorization/capabilities`. The snapshot has a schema version, an authorization revision, the principal id, a stable role key, and server-owned role presentation. The snapshot has three scopes: | Scope | Examples | | - | - | | Global | Create workspaces, manage gateway settings, manage providers, skills, MCP, invitations, members, or own sessions. | | Workspace | Read or manage the workspace, create threads, use providers and runtimes, run tasks, read or write artifacts, and manage workspace members. | | Thread | Read, write, edit or delete an own message, start or observe turns, answer requests, steer or cancel execution, manage participants, and control tasks or artifacts. | The workspace projection also contains the operational resources the principal may use. Providers, provider models, CLI runtimes, CLI models, skills, and MCP servers are represented either by `all` or by exact stable ids. The client should filter selectors from this projection rather than guessing from a role name. Capability snapshots also carry server-enforced execution limits, agent permission presets, artifact attachment permission, and MCP invocation limits. These fields are useful for disabling unavailable controls, but the gateway repeats authorization and policy checks at every mutating boundary. Role presentation is display data. A client may show the role label and description, but it must not derive access from `role_key`, `principal kind`, or a locally maintained role enum. The gateway may return a future role presentation that an older client does not know. ## Workspace and thread access Every workspace and thread operation is checked against the authenticated principal, current membership, visibility, and the authorization revision captured by the request. Thread access is narrower than workspace access. A member can be allowed to read a workspace while lacking access to a private thread or to its participant list. When access changes, the gateway invalidates the affected projections and publishes `access/changed`, `authorization/projection_changed`, `workspace/members_changed`, `member/changed`, or `thread/participants/changed` as appropriate. Notifications are hints. After reconnect or a revision change, clients should reload the capability snapshot and the affected resource. Agent and task work does not bypass these checks. A detached task keeps the authorization facts needed for its run, but task admission, artifact access, child-thread access, delivery, and review are checked again against the stored context. ## Invitations and membership Invitations are scoped grants, not gateway passwords. An invitation has an inviter, a role presentation, one to 64 workspace grants, an expiry, and a gateway-bound credential. The default invitation lifetime is seven days. Credentials use the `pinv1_` prefix and are returned in a protected app deep link when the client supports it. The accept flow is: 1. The recipient previews the invitation through the restricted exchange transport. 2. The client displays the gateway, inviter, role, workspaces, expiry, and transport security. 3. The recipient submits a profile and installation descriptor. 4. The gateway accepts the invitation, creates or links the principal and member records, creates a device session, and returns the granted workspace ids. The gateway id in an invitation must match the gateway that receives the acceptance. TLS gateways use `wss`; loopback or explicitly configured plaintext endpoints use `ws`. The transport state is part of the preview so a client can show it before acceptance. Member suspension and removal are terminal access changes. Suspension revokes active sessions while retaining the member record for restoration. Removal revokes sessions, removes workspace membership, changes affected private-thread access, and invalidates related invitations. The gateway publishes the corresponding access and lifecycle events after the durable change commits. ## Security boundaries in the code The important boundaries are: * `crates/gateway/src/auth` authenticates credentials and owns session lifecycle. * `crates/gateway/src/authorization` resolves role, workspace, thread, agent, and resource access. * `crates/gateway/src/message/auth_handlers.rs`, `invitation_handlers.rs`, and `member_handlers.rs` implement JSON-RPC handlers. * `crates/protocol/src/auth.rs`, `authorization.rs`, `invitation.rs`, and `member.rs` define the public DTOs and validation rules. * `crates/client` stores the projected session and capability state used by both shells. * `crates/client-ffi` exposes the shared state to the React Native application. The normal WebSocket transport carries an authenticated session. Restricted credential exchanges are separated from normal authorization so an unauthenticated caller cannot reach an ordinary handler with a fabricated role or session. ## Related pages * [Authentication and access API](https://docs.getpioneer.dev/protocol/auth.md) lists auth, invitation, member, and capability methods. * [Permission system](https://docs.getpioneer.dev/architecture/permissions.md) explains per-turn tool policy after access has been admitted. * [Agent domain](https://docs.getpioneer.dev/architecture/agent-domain.md) explains non-human identities, execution authorship, and delegation routes. * [Gateway architecture](https://docs.getpioneer.dev/architecture/gateway.md) explains request dispatch and notification fan-out. * [Persistence layer](https://docs.getpioneer.dev/architecture/persistence.md) explains where identity and session state is stored. * [Secret storage](https://docs.getpioneer.dev/architecture/secrets.md) explains why credentials are not ordinary settings data. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.