List user organizations
List organizations the current user is a member of, oldest membership first.
/api/orgsCookie session from Better Auth. Requires X-Org-Id header for org-scoped routes.
In: cookie
Header Parameters
Preview the API as a lesser role ("view as"). One value, ;-separated key=value pairs; whitespace around the separators is tolerated and nothing else is:
org_role(required) —memberorguest. Previewingowner/adminis refused.space(optional) — aspc_space id. Must be paired withrole.role(optional) —preset:<admin|builder|operator|runner|viewer>orcustom:<srl_ id>. Must be paired withspace.
Example: org_role=member; space=spc_…; role=preset:viewer.
The persona is enforced server-side: permissions, the space role and every listing are the persona's, and a write the persona cannot make is refused exactly as it would be for a real holder of that role. The authenticated identity and the audit actor stay the real caller; audit rows carry the persona under after.viewAs.
Refusals — never a silent fall-back to the caller's real permissions: 400 invalid_view_as (header does not parse), 400 view_as_unsupported (the credential is not one that can carry a persona — only a cookie session and the CLI/instance token, which authenticate the user themselves, can), 403 view_as_forbidden (the real org role is not owner/admin, or the role is not one the caller could grant in that space), 404 view_as_not_found (the space is not in the org, the custom role does not exist, or the organization named alongside the persona is not one the caller belongs to). A 404 carrying view_as_not_found means the PREVIEW died and must be dropped; a plain 404 not_found under an active persona is the previewed role's own wall and leaves the preview standing.
On GET /api/orgs and GET /api/me/orgs — the two listings exempt from X-Org-Id — the X-Org-Id header names the organization the persona applies to; every other row in those listings stays the caller's real role. Sending the persona without it is 400 invalid_view_as, and naming an organization the caller is not a member of is 404 view_as_not_found: a listing that answered with real permissions while the client believed it was previewing would be the failure this feature exists to prevent.
The Server-Sent-Events routes (/api/realtime/*) take the same value as the view_as QUERY parameter instead: EventSource cannot send headers.
Every response produced under a validated persona carries X-View-As-Active: 1.
curl -X GET "https://your-instance/api/orgs"{
"object": "list",
"hasMore": false,
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Acme Corp",
"slug": "acme-corp",
"role": "owner",
"permissions": [
"org:read",
"org:update",
"members:invite"
],
"createdAt": "2026-01-10T08:00:00Z",
"deleting_at": null
}
]
}{
"type": "https://docs.appstrate.dev/errors/invalid-view-as",
"title": "Invalid View-As Header",
"status": 400,
"detail": "X-View-As could not be parsed: space and role must be provided together",
"code": "invalid_view_as",
"param": "X-View-As",
"request_id": "req_abc123"
}{
"type": "https://docs.appstrate.dev/errors/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Invalid or missing session",
"code": "unauthorized",
"request_id": "req_abc123"
}{
"type": "https://docs.appstrate.dev/errors/forbidden",
"title": "Forbidden",
"status": 403,
"detail": "Insufficient permissions",
"code": "forbidden",
"request_id": "req_abc123"
}{
"type": "https://docs.appstrate.dev/errors/not-found",
"title": "Not Found",
"status": 404,
"detail": "Resource not found",
"code": "not_found",
"request_id": "req_abc123"
}