#Orgs

---

#GET /orgs

List organizations the caller is a member of

Auth: Bearer token required

Responses

Status	Description	Schema
200	OK	OrgList
401	Unauthorized	Error
403	Forbidden	Error

---

#POST /orgs

Create an organization

Auth: Bearer token required

Request body (application/json)

Field	Type	Description
name	string	Display name (required)
slug	string	URL slug (lowercase, hyphens only) (required)

Responses

Status	Description	Schema
201	Created	Organization
401	Unauthorized	Error
403	Forbidden	Error
409	Conflict	Error

---

#GET /orgs/{id}

Get an organization by id or slug

Org membership required.

Auth: Bearer token required

Path parameters

Name	Type	Description
id	string	Organization ID or slug

Responses

Status	Description	Schema
200	OK	Organization
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#PATCH /orgs/{id}

Rename an organization

Org owner/admin only.

Auth: Bearer token required

Path parameters

Name	Type	Description
id	string	Organization ID or slug

Request body (application/json)

Field	Type	Description
name	string	Display name (required)

Responses

Status	Description	Schema
200	OK	Organization
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#DELETE /orgs/{id}

Delete an organization

Org owner only.

Auth: Bearer token required

Path parameters

Name	Type	Description
id	string	Organization ID or slug

Responses

Status	Description	Schema
200	OK	object
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#GET /orgs/{id}/users

List organization members

Org membership required.

Auth: Bearer token required

Path parameters

Name	Type	Description
id	string	Organization ID or slug

Responses

Status	Description	Schema
200	OK	OrgUserList
401	Unauthorized	Error
403	Forbidden	Error

---

#POST /orgs/{id}/users

Provision and add a member

Org owner/admin only. Provisions (or upserts) a user and adds them to the org with the given role.

Auth: Bearer token required

Path parameters

Name	Type	Description
id	string	Organization ID or slug

Request body (application/json)

Field	Type	Description
email	string(email)	User email (required)
name	string	User full name (required)
role	owner | admin | member	Role (owner|admin|member)

Responses

Status	Description	Schema
201	Created	object
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#PATCH /orgs/{id}/users/{userId}

Change a member's role

Org owner/admin only. Cannot demote the last owner.

Auth: Bearer token required

Path parameters

Name	Type	Description
id	string	Organization ID or slug
userId	string	User ID

Request body (application/json)

Field	Type	Description
role	owner | admin | member	New role (required)

Responses

Status	Description	Schema
200	OK	object
400	Bad Request	Error
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#DELETE /orgs/{id}/users/{userId}

Remove a member

Org owner/admin only. Cascades project memberships and personal tokens scoped to the org. Cannot remove the last owner.

Auth: Bearer token required

Path parameters

Name	Type	Description
id	string	Organization ID or slug
userId	string	User ID

Responses

Status	Description	Schema
200	OK	object
400	Bad Request	Error
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#POST /orgs/{id}/leave

Leave an organization

Org membership required. The current user removes themselves. The last owner cannot leave.

Auth: Bearer token required

Path parameters

Name	Type	Description
id	string	Organization ID or slug

Responses

Status	Description	Schema
200	OK	object
400	Bad Request	Error
401	Unauthorized	Error
403	Forbidden	Error

---

#GET /orgs/{id}/sso-extras

List org SSO extras

Org owner/admin only. Per-provider settings (e.g. forceSso) not covered by the better-auth SSO plumbing.

Auth: Bearer token required

Path parameters

Name	Type	Description
id	string	Organization ID or slug

Responses

Status	Description	Schema
200	OK	OrgSsoExtraList
401	Unauthorized	Error
403	Forbidden	Error

---

#PATCH /orgs/{id}/sso-extras/{providerId}

Toggle force-SSO for an org SSO provider

Org owner/admin only.

Auth: Bearer token required

Path parameters

Name	Type	Description
id	string	Organization ID or slug
providerId	string	SSO provider ID

Request body (application/json)

Field	Type	Description
forceSso	boolean	Force-SSO toggle for this provider (required)

Responses

Status	Description	Schema
200	OK	object
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#GET /orgs/{id}/invitations

List organization invitations

Org membership required.

Auth: Bearer token required

Path parameters

Name	Type	Description
id	string	Organization ID or slug

Responses

Status	Description	Schema
200	OK	OrgInvitation[]
400	Bad Request	Error
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#POST /orgs/{id}/invitations

Invite a user to an organization

Org owner/admin only. Returns a copyable acceptUrl; email delivery is best-effort and never blocks creation.

Auth: Bearer token required

Path parameters

Name	Type	Description
id	string	Organization ID or slug

Request body (application/json)

Field	Type	Description
email	string(email)	Invitee email (required)
role	owner | admin | member	Role to grant on acceptance (required)
resend	boolean	Re-send when an invitation already exists

Responses

Status	Description	Schema
201	Created	OrgInvitation
400	Bad Request	Error
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#DELETE /orgs/{id}/invitations/{invitationId}

Cancel an organization invitation

Org owner/admin only.

Auth: Bearer token required

Path parameters

Name	Type	Description
id	string	Organization ID or slug
invitationId	string	Invitation ID

Responses

Status	Description	Schema
200	OK	object
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#POST /orgs/invitations/{token}/accept

Accept an organization invitation

Creates the membership with the invitation's role and marks the invitation accepted. The caller need not already belong to the org — this is how they join it. Pending/expiry/invitee-email checks are in-handler (spec route-contracts #299 §15.3).

Auth: Bearer token required

Path parameters

Name	Type	Description
token	string	Invitation ID (from its acceptUrl)

Responses

Status	Description	Schema
201	Created	OrgInvitationAcceptance
400	Bad Request	Error
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

#Schemas

#Error

Field	Type	Description
error	string	(required)
code	string

#OrgInvitation

Field	Type	Description
id	string	(required)
email	string	(required)
role	string	(required)
status	string	(required)
expiresAt	string	(required)
createdAt	string	(required)
inviterId	string	(required)
organizationId	string	(required)
acceptUrl	string	(required)

#OrgInvitationAcceptance

Field	Type	Description
id	string	(required)
organizationId	string	(required)
userId	string	(required)
role	owner | admin | member	(required)
createdAt	string | string	(required)

#OrgList

Type: Organization[]

#OrgSsoExtraList

Type: object[]

#OrgUserList

Type: object[]

#Organization

Field	Type	Description
id	string	(required)
name	string	(required)
slug	string	(required)
logo	string | null	(required)
createdAt	string | string	(required)
metadata	object | null	(required)
suspendedAt	string | string | null	(required)