Organizations

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

From your backend: secret key

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, Friday, August 28, 2026