---
title: "GET /v1/principals"
method: GET
path: "/v1/principals"
---

# GET /v1/principals

`GET /v1/principals`

## Request

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

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

## Response `200`

The request has succeeded.

- Principal[]
  - `id` string, required
  - `kind` 'human' | 'agent', required
  - `name` string, required: What the org calls this principal. Display and audit only.
  - `userId` string, nullable, required: Humans: the member's user id. Null for agents — nobody is behind one.
  - `oauthClientId` string, 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`).
  - `orgCapabilities` string[], 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.
  - `createdBy` string, nullable, required: Agents: the member who minted it. Null for humans.
  - `expiresAt` string, date-time, nullable, required: Always null. Kept so a client reading this field does not break; nothing sets it.
  - `enrolledAt` string, date-time, nullable, required
  - `revokedAt` string, date-time, nullable, required
  - `createdAt` string, date-time, required

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/foundermail/apis/org.md) - [All operations](https://skmtc.dev/foundermail/apis/org/llms.txt) - [OpenAPI document](https://skmtc.dev/foundermail/apis/org/revisions/8bbb36e378ab?raw)