> ## 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. # Authentication and access API > JSON-RPC methods for device activation, sessions, invitations, membership, profiles, and capability snapshots. Pioneer authenticates client installations through device activation and session credentials. The gateway then evaluates the current principal, workspace membership, thread visibility, and capability projection for every normal method. The public credential flow is not a shared superuser token. Access credentials are short lived, refresh credentials are rotated, and session state can be revoked independently. See [Identity, authentication, and authorization](https://docs.getpioneer.dev/architecture/identity-and-authorization.md) for the implementation model. ## Method groups | Method | Params | Result | Purpose | | - | - | - | - | | `auth/me` | `AuthMeParams` | `AuthMeResponse` | Return gateway, principal, device, session, and optional role snapshots. | | `authorization/capabilities` | `AuthorizationCapabilitiesParams` | `AuthorizationCapabilitySnapshot` | Return global, workspace, thread, resource, and execution capabilities. | | `auth/profile/update` | `AuthProfileUpdateParams` | `AuthProfileUpdateResponse` | Update the authenticated principal's display name, nickname, or avatar. | | `auth/session/list` | `AuthSessionListParams` | `AuthSessionListResponse` | List the principal's device sessions. | | `auth/session/revoke` | `AuthSessionRevokeParams` | `AuthSessionRevokeResponse` | Revoke one session, with an optional expected status. | | `auth/logout` | `AuthLogoutParams` | `AuthLogoutResponse` | Revoke the current session. | | `auth/device/create` | `AuthDeviceCreateParams` | `AuthDeviceCreateResponse` | Create a pending device session and one-time activation code. | | `auth/refresh` | `AuthRefreshParams` | `AuthRefreshGrant` | Exchange a refresh credential for rotated access and refresh credentials. Restricted transport. | | `auth/device/activate` | `AuthDeviceActivateParams` | `AuthSessionGrant` | Activate a client installation with a pending device code. Restricted transport. | | `invite/create` | `InvitationCreateParams` | `InvitationCreateResponse` | Create a gateway-bound invitation with role and workspace grants. | | `invite/list` | `InvitationListParams` | `InvitationListResponse` | List invitations visible to the caller. | | `invite/revoke` | `InvitationRevokeParams` | `InvitationRevokeResponse` | Revoke a pending invitation. | | `invite/preview` | `InvitationPreviewParams` | `InvitationPreviewResponse` | Inspect an invitation before profile creation. Restricted transport. | | `invite/accept` | `InvitationAcceptParams` | `InvitationAcceptResponse` | Accept an invitation and create the recipient session. Restricted transport. | | `member/list` | `MemberListParams` | `MemberListResponse` | List the gateway member directory. | | `member/suspend` | `MemberSuspendParams` | `MemberSuspendResponse` | Suspend a principal and revoke its active sessions. | | `member/restore` | `MemberRestoreParams` | `MemberRestoreResponse` | Restore a suspended principal. | | `member/remove` | `MemberRemoveParams` | `MemberRemoveResponse` | Remove a principal and its retained access. | | `member/device/create` | `MemberDeviceCreateParams` | `MemberDeviceCreateResponse` | Create an activation for another member's device when allowed. | | `workspace/member/list` | `WorkspaceMemberListParams` | `WorkspaceMemberListResponse` | List members of one workspace. | | `workspace/member/add` | `WorkspaceMemberAddParams` | `WorkspaceMemberAddResponse` | Add an existing principal to a workspace. | | `workspace/member/remove` | `WorkspaceMemberRemoveParams` | `WorkspaceMemberRemoveResponse` | Remove a principal from a workspace. | The normal transport accepts the authenticated methods above except the four restricted exchanges. A client must not expose restricted methods through a normal authorized request path. ## Device activation contract `auth/device/create` creates a pending device and session. The response includes: * `device_id` and `session_id`; * the gateway id; * a one-time `activation_code`; * `expires_at_unix`. The CLI equivalent is: ```bash theme={null} pioneer device create pioneer device create --json ``` `auth/device/activate` receives a `ClientInstallationDescriptor`: ```json theme={null} { "installation_id": "desktop-installation-1", "display_name": "Work laptop", "client_kind": "desktop", "platform": "macos", "client_version": "0.46.0" } ``` The activation exchange returns `AuthSessionGrant`. It contains gateway, principal, device, and session snapshots, access and refresh credentials, both expiries, the refresh generation, protocol version, and the required credential storage order. Activation codes are eight symbols, expire after ten minutes by default, and are limited to five failed attempts. Clients should clear the code after a successful or terminally failed exchange. ## Refresh and revocation `AuthRefreshParams` contains a durable `refresh_request_id` and an optional client version. A successful response rotates the refresh credential and advances its generation. Clients must persist the new refresh credential before relying on the new access credential. The current refresh credential format uses the `prf2_` prefix. Its value is a secret string and is redacted by `Debug` implementations. The protocol does not make clients responsible for JWT signing or validation. Session revocation reasons include logout, self-revocation, device revocation, activation-attempt exhaustion, refresh reuse, principal suspension or removal, supersession, and security reset. Termination notifications classify session revoked, expired, compromised, suspended principal, and removed principal separately. ## Profile and sessions `auth/profile/update` accepts a display name, nickname, and avatar action. The display name is bounded to 128 characters. Nicknames are 2 to 32 ASCII characters and use the pattern `[A-Za-z0-9][A-Za-z0-9_.-]{1,31}`. Avatar media is validated and bounded before it is stored. `auth/session/list` returns device and session snapshots, a `current` flag, and the last-seen timestamp. A client can show the list without receiving raw credentials. `auth/session/revoke` takes an optional `expected_status` so a stale settings screen does not accidentally apply a state transition it did not observe. ## Capability snapshots `authorization/capabilities` accepts optional `workspace_id` and `thread_id`. The response includes: * schema version and authorization revision; * principal id, role key, and server-owned role presentation; * global management capabilities; * workspace capabilities and execution limits; * allowed providers, models, runtimes, skills, and MCP servers; * agent permission presets and locked fields; * thread capabilities when a thread was requested; * artifact and MCP invocation limits. The response is a projection, not an authorization grant that a client can modify. The gateway rechecks the same decision at method admission and at delayed task or agent execution boundaries. ## Invitations Invitations expire after seven days by default and grant between one and 64 workspaces. Their credential uses the `pinv1_` prefix and can be embedded in a `pioneer://invite` URI. The gateway id, base URL, role presentation, workspaces, expiry, and transport security are available from preview before acceptance. `invite/preview` and `invite/accept` use the restricted exchange transport. On acceptance, the caller submits the new member profile and installation descriptor. The response contains the new or linked principal, member, granted workspaces, device, session, and credentials. ## Member lifecycle Member directory pages default to 50 rows and allow up to 100. Member lifecycle methods accept a principal id and use expected status where the operation needs compare-and-set behavior. Suspending a member revokes its active sessions and publishes access and member changes. Removing a member also removes workspace access, invalidates related invitations, and changes private-thread access. Clients should handle these events by clearing stale projections rather than keeping a locally editable member row. ## Notifications | Event | Meaning | | - | - | | `access/changed` | A principal's effective access changed. | | `authorization/projection_changed` | A capability projection must be reloaded. | | `invitation/changed` | An invitation was created, revoked, accepted, or expired. | | `member/changed` | A member profile or lifecycle state changed. | | `workspace/members_changed` | Workspace membership changed. | | `auth/session_revoked` | A session can no longer be used. | | `auth/access_expiring` | The current access credential is nearing expiry. | Events are invalidation signals. After reconnect, reload `auth/me`, `authorization/capabilities`, and the affected member, invitation, workspace, or thread resource. ## Generated schemas The protocol schema generator emits these standalone schemas for this surface: * `/schemas/auth_me_response.json` * `/schemas/authorization_capability_snapshot.json` `AuthSessionGrant`, `AuthRefreshGrant`, activation request and response types, invitation presentations, member summaries, and authentication notifications are used by the auth transport but are not emitted as standalone files by the current protocol schema generator. Client projection schemas are generated separately under `/schemas/client/`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.