Authentication and access API

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 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:

pioneer device create
pioneer device create --json

auth/device/activate receives a ClientInstallationDescriptor:

{
  "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/.

Introduction

Workspace & Threads

Features

Authentication and access API

Method groups

Device activation contract

Refresh and revocation

Profile and sessions

Capability snapshots

Invitations

Member lifecycle

Notifications

Generated schemas

​Method groups

​Device activation contract

​Refresh and revocation

​Profile and sessions

​Capability snapshots

​Invitations

​Member lifecycle

​Notifications

​Generated schemas

Method groups

Device activation contract

Refresh and revocation

Profile and sessions

Capability snapshots

Invitations

Member lifecycle

Notifications

Generated schemas