Organizations

Creating teams from your backend, and managing them from your app.

From your backend: secret key

Creating one:

{ "name": "Acme Corp", "slug": "acme", "createdBy": "usr_..." }

createdBy becomes the owner. An organization with no owner is one nobody can administer, so the two are created together.

GET /v1/organizations?userId=usr_... lists what one person belongs to. GET /v1/organizations/{organizationId} returns the organization with its members.

Renaming or changing the image:

{ "name": "Acme", "slug": "acme", "imageUrl": null }

Omitting a field leaves it alone; null clears it. imageUrl must be an image you uploaded through us. We do not load images from other hosts: that host would see everyone who views it, and the file behind a link can change after you set it.

DELETE /v1/organizations/{organizationId} removes the organization and its memberships. The people survive.

No permission check applies to these: a secret key owns the environment, so there is no membership to consult. The equivalent calls made with a session token do check, because there the caller is a person whose standing can change.

Full administrative control over any organization in the environment.

From your app: session token

These act on the organization the session is currently acting as, so there is no id in the path.

Adding somebody:

{ "email": "colleague@example.com", "role": "member" }

They must already have an account in your environment. If they do not, the error says so. The caller is an authenticated admin adding a colleague, and being vague there would just leave them retyping an address that was never going to work.

Renaming it, or changing its picture:

{ "name": "Acme Corp", "imageUrl": "https://assets.example.com/acme.png" }

This needs org:manage, which is a different permission from org:members:manage. Plenty of teams want people who can invite colleagues without being able to rename the company on every screen in the product.

imageUrl must be https. Send null to remove it; omitting the field leaves it alone. To upload rather than link, ask for a ticket at POST /v1/me/assets/upload-url with purpose: "organization_image", then save the URL it returns here.

Two rules apply to removal:

Anybody may remove themselves. Leaving needs no permission, because an organization you cannot leave is a trap.

The last owner cannot be removed, by anyone including themselves, or the organization would be left with nobody able to administer it.

{ "error": { "code": "forbidden", "message": "Cannot remove the last owner. Transfer ownership first." } }

Updated at, Wednesday, October 21, 2026