Everyone access can be granted to: the organisation's humans and its agents, oldest first.

get/v1/principals

Request

  • The document declares no server URL.
  • Auth: one of:
    • HTTP bearer
    • API key in cookie __Secure-better-auth.session_token

Response

The request has succeeded.

idstring required
kind'human' | 'agent' required
namestring required

What the org calls this principal. Display and audit only.

userIdstring nullable required

Humans: the member's user id. Null for agents — nobody is behind one.

oauthClientIdstring nullable required

Agents: the OAuth client this principal IS. Null for humans.

Minted with the principal, not claimed later: the authorization server holds a per-client capability ceiling and refuses to issue against an empty one, so the client cannot reach a mailbox before a grant says it may. That server-owned ceiling is what the one-time enrolment code used to stand in for.

status'enrolled' | 'active' | 'revoked' required

Agents are enrolled from birth (→ revoked); humans are active (→ revoked).

orgCapabilitiesstring[] required

What this principal may do to the ESTATE, as opposed to what it may do with a mailbox.

Empty for every human — a person's authority over the organisation is their membership ROLE, resolved per request, and they never authenticate as an OAuth client. For an agent it is the ceiling an admin set at creation, and it is published because an agent that can create mailboxes is an agent that can spend this organisation's capacity: that should be visible on the list, not buried in a token.

createdBystring nullable required

Agents: the member who minted it. Null for humans.

expiresAtstring date-time nullable required

Always null. Kept so a client reading this field does not break; nothing sets it.

enrolledAtstring date-time nullable required
revokedAtstring date-time nullable required
createdAtstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.