English
Members and invitations
Routes are relative to <PUBLIC_BASE_URL>; request and response bodies are JSON unless stated otherwise. Authentication, scopes, pagination and the error format are described in the REST API guides.
GET /api/v1/admin/members
List the members
Every member of the instance, with status, role and counters.
Access — Member session or API key with scope admin:read (administrator role required).
Responses
200 — The members.
| Field | Type | Required |
|---|---|---|
members | object[] | yes |
JSON Schema
json
{
"type": "object",
"properties": {
"members": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"email": { "type": "string" },
"name": { "type": "string" },
"role": { "type": "string", "enum": [ "member", "admin" ] },
"status": { "type": "string", "enum": [ "active", "suspended" ] },
"mailboxCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"publishedWorkflowCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"email",
"name",
"role",
"status",
"mailboxCount",
"publishedWorkflowCount",
"createdAt"
],
"additionalProperties": false
}
}
},
"required": [ "members" ],
"additionalProperties": false
}401 — No valid session or API key (auth.unauthenticated).
403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).
429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.
PATCH /api/v1/admin/members/{id}
Change a member’s role
The instance keeps at least one active administrator: demoting the last one is refused. Recorded in the audit log.
Access — Member session or API key with scope admin:write (administrator role required).
Parameters
| Name | In | Type | Required |
|---|---|---|---|
id | path | string | yes |
Request body (application/json)
| Field | Type | Required |
|---|---|---|
role | "member" | "admin" | yes |
JSON Schema
json
{
"type": "object",
"properties": { "role": { "type": "string", "enum": [ "member", "admin" ] } },
"required": [ "role" ]
}Responses
200 — The member.
| Field | Type | Required |
|---|---|---|
member | object | yes |
JSON Schema
json
{
"type": "object",
"properties": {
"member": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"email": { "type": "string" },
"name": { "type": "string" },
"role": { "type": "string", "enum": [ "member", "admin" ] },
"status": { "type": "string", "enum": [ "active", "suspended" ] },
"mailboxCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"publishedWorkflowCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"email",
"name",
"role",
"status",
"mailboxCount",
"publishedWorkflowCount",
"createdAt"
],
"additionalProperties": false
}
},
"required": [ "member" ],
"additionalProperties": false
}400 — The request does not match its schema.
401 — No valid session or API key (auth.unauthenticated).
403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).
429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.
Error codes — request.bad_request, governance.not_found, governance.last_admin. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.
POST /api/v1/admin/members/{id}/deactivate
Deactivate a member
Revokes the sessions, disconnects the mailboxes and unpublishes the workflows; the response lists what was actually cut. An administrator cannot deactivate themselves nor the last active administrator.
Access — Member session or API key with scope admin:write (administrator role required).
Parameters
| Name | In | Type | Required |
|---|---|---|---|
id | path | string | yes |
Responses
200 — The member and the effects.
| Field | Type | Required |
|---|---|---|
member | object | yes |
effects | object | yes |
JSON Schema
json
{
"type": "object",
"properties": {
"member": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"email": { "type": "string" },
"name": { "type": "string" },
"role": { "type": "string", "enum": [ "member", "admin" ] },
"status": { "type": "string", "enum": [ "active", "suspended" ] },
"mailboxCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"publishedWorkflowCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
}
},
"required": [
"id",
"email",
"name",
"role",
"status",
"mailboxCount",
"publishedWorkflowCount",
"createdAt"
],
"additionalProperties": false
},
"effects": {
"type": "object",
"properties": {
"sessionsRevoked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"mailboxesPaused": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"workflowsUnpublished": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
},
"required": [ "sessionsRevoked", "mailboxesPaused", "workflowsUnpublished" ],
"additionalProperties": false
}
},
"required": [ "member", "effects" ],
"additionalProperties": false
}401 — No valid session or API key (auth.unauthenticated).
403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).
429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.
Error codes — governance.not_found, governance.self_target, governance.last_admin. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.
POST /api/v1/admin/members/{id}/reactivate
Reactivate a member
The account becomes usable again, and nothing else: mailboxes stay disconnected and workflows unpublished.
Access — Member session or API key with scope admin:write (administrator role required).
Parameters
| Name | In | Type | Required |
|---|---|---|---|
id | path | string | yes |
Responses
200 — The member.
| Field | Type | Required |
|---|---|---|
member | object | yes |
Same schema as PATCH /api/v1/admin/members/{id}.
401 — No valid session or API key (auth.unauthenticated).
403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).
429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.
Error codes — governance.not_found. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.
GET /api/v1/admin/members/invitations
List pending invitations
Access — Member session or API key with scope admin:read (administrator role required).
Responses
200 — The invitations.
| Field | Type | Required |
|---|---|---|
invitations | object[] | yes |
JSON Schema
json
{
"type": "object",
"properties": {
"invitations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"email": { "type": "string" },
"role": { "type": "string", "enum": [ "member", "admin" ] },
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"invitedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{ "type": "null" }
]
},
"expired": { "type": "boolean" }
},
"required": [
"id",
"email",
"role",
"expiresAt",
"createdAt",
"invitedBy",
"expired"
],
"additionalProperties": false
}
}
},
"required": [ "invitations" ],
"additionalProperties": false
}401 — No valid session or API key (auth.unauthenticated).
403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).
429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.
POST /api/v1/admin/members/invitations
Invite a member
Creates the invitation and returns the acceptance link: the only place a clear token leaves the instance. The invitation is not emailed; the administrator passes the link on. Refused when a member or a pending invitation already exists for the address.
Access — Member session or API key with scope admin:write (administrator role required).
Request body (application/json)
| Field | Type | Required |
|---|---|---|
email | string | yes |
role | "member" | "admin" | no |
JSON Schema
json
{
"type": "object",
"properties": {
"email": { "type": "string" },
"role": { "default": "member", "type": "string", "enum": [ "member", "admin" ] }
},
"required": [ "email" ]
}Responses
201 — The invitation and its link.
| Field | Type | Required |
|---|---|---|
invitation | object | yes |
acceptUrl | string (uri) | yes |
token | string | yes |
JSON Schema
json
{
"type": "object",
"properties": {
"invitation": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"email": { "type": "string" },
"role": { "type": "string", "enum": [ "member", "admin" ] },
"expiresAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"createdAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
},
"invitedBy": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{ "type": "null" }
]
},
"expired": { "type": "boolean" }
},
"required": [
"id",
"email",
"role",
"expiresAt",
"createdAt",
"invitedBy",
"expired"
],
"additionalProperties": false
},
"acceptUrl": { "type": "string", "format": "uri" },
"token": { "type": "string", "minLength": 1 }
},
"required": [ "invitation", "acceptUrl", "token" ],
"additionalProperties": false
}400 — The request does not match its schema.
401 — No valid session or API key (auth.unauthenticated).
403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).
429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.
This operation accepts an Idempotency-Key header: replaying the same request with the same key returns the original response instead of acting twice. See Idempotency.
Error codes — request.bad_request, governance.member_exists, governance.invitation_exists. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.
Example request
json
{ "email": "bob@example.test", "role": "member" }Example response (201)
json
{
"invitation": {
"id": "0192f1c2-3b4d-7e8f-9a0b-1c2d3e4f5a6b",
"email": "bob@example.test",
"role": "member",
"invitedBy": "0192f1c2-0000-7000-8000-000000000001",
"createdAt": "2026-10-04T09:00:00.000Z",
"expiresAt": "2026-10-11T09:00:00.000Z",
"status": "pending"
},
"acceptUrl": "https://mail.example.test/invite/Qm9uam91cl9jZXN0X3VuX2V4ZW1wbGU",
"token": "Qm9uam91cl9jZXN0X3VuX2V4ZW1wbGU"
}DELETE /api/v1/admin/members/invitations/{id}
Revoke an invitation
An invitation already consumed or unknown is a 404 and leaves no trace; a revocation is recorded in the audit log.
Access — Member session or API key with scope admin:write (administrator role required).
Parameters
| Name | In | Type | Required |
|---|---|---|---|
id | path | string | yes |
Responses
204 — Revoked.
401 — No valid session or API key (auth.unauthenticated).
403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).
429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.
Error codes — governance.not_found. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.