---
title: Organizations
description: Creating teams from your backend, and managing them from your app.
---

import Endpoint from '../../../components/Endpoint.astro';
import Callout from '../../../components/Callout.astro';

## From your backend: secret key

<Endpoint method="POST" path="/v1/organizations" />
<Endpoint method="GET" path="/v1/organizations" />
<Endpoint method="POST" path="/v1/organizations/{organizationId}/members" />
<Endpoint method="DELETE" path="/v1/organizations/{organizationId}/members/{userId}" />

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.

<Endpoint method="GET" path="/v1/me/organizations" />
<Endpoint method="PATCH" path="/v1/me/organization" />
<Endpoint method="GET" path="/v1/me/organization/members" />
<Endpoint method="POST" path="/v1/me/organization/members" />
<Endpoint method="PATCH" path="/v1/me/organization/members/{userId}" />
<Endpoint method="DELETE" path="/v1/me/organization/members/{userId}" />

Adding somebody:

```json
{ "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:

```json
{ "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`](/api/users/#ask-for-an-upload-url) with
`purpose: "organization_image"`, then save the URL it returns here.

<Callout type="warning">
Permission is checked against the **live membership**, not the token's claims.
Claims are a snapshot: an admin demoted a minute ago still presents a token
saying they can manage members. That is tolerable for deciding what to draw and
not tolerable for removing somebody from a company.
</Callout>

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.

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