Install the agent a founder has just consented to. Idempotent per (organisation, client).

post/v1/consents

Request

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

Request body

clientIdstring required

The OAuth client from the authorize request the founder is answering. Under client-id metadata documents this is an HTTPS URL naming the agent PRODUCT, which is why the same value legitimately appears in many organisations.

namestring required

What this organisation will call the agent. Display and audit only.

orgCapabilitiesstring[]

The estate ceiling approved on the CONTROL surface's screen. Omitted means none.

⚠️ Narrowed to the known org.* vocabulary on arrival rather than trusted — this comes from a screen, and a scope the resource server does not enforce would be a ceiling raised by whoever typed it.

Response

The request has succeeded and a new resource has been created as a result.

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.