> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations

> Create organizations and manage members, roles, and invitations.

An organization is the top of the resource hierarchy — it owns environments, tenants, billing, and the people who work in it. Organization administration is a dashboard operation, so every endpoint here requires a **user session**.

<Note>
  All endpoints on this page are **\[User]** — they require a signed-in user session and are not available to API keys. See [Authentication](/developers/authentication#user-sessions).
</Note>

## Roles

Members hold one role per organization, which determines what they can do:

| Role            | Can do                                                              |
| --------------- | ------------------------------------------------------------------- |
| `owner`         | Everything, including deleting the organization and changing roles. |
| `billing_admin` | Manage billing and most administration below ownership.             |
| `developer`     | Work with environments, tenants, and content.                       |
| `viewer`        | Read-only access.                                                   |

See [Members & roles](/teams/members-roles) for the full permission matrix.

## Endpoints

| Method   | Path                                    | Description                                       | Auth    |
| -------- | --------------------------------------- | ------------------------------------------------- | ------- |
| `GET`    | `/organizations`                        | List organizations the user belongs to, with role | \[User] |
| `GET`    | `/organizations/:id`                    | Get a single organization                         | \[User] |
| `POST`   | `/organizations`                        | Create an organization                            | \[User] |
| `PATCH`  | `/organizations/:id`                    | Update name or status                             | \[User] |
| `DELETE` | `/organizations/:id`                    | Delete an organization                            | \[User] |
| `GET`    | `/organizations/:id/members`            | List members and pending invites                  | \[User] |
| `POST`   | `/organizations/:id/members`            | Invite a member by email                          | \[User] |
| `POST`   | `/organizations/:id/members/role`       | Assign or change a member's role                  | \[User] |
| `DELETE` | `/organizations/:id/members/:member_id` | Remove a member                                   | \[User] |
| `DELETE` | `/organizations/:id/invites/:invite_id` | Revoke a pending invite                           | \[User] |

***

### List organizations

`GET /organizations`

Returns every organization the signed-in user belongs to, each with the user's role in it.

```bash theme={null}
curl "https://api.autosage.ai/api/v1/organizations" \
  -H "Cookie: YOUR_SESSION_COOKIE"
```

***

### Get an organization

`GET /organizations/:id`

<ParamField path="id" type="string" required>
  The organization ID.
</ParamField>

***

### Create an organization

`POST /organizations`

Creates an organization and auto-provisions a default environment, a default tenant inside it, and a starting credit balance — so you can begin working immediately.

<ParamField body="name" type="string" required>
  Display name for the organization.
</ParamField>

<ParamField body="slug" type="string" required>
  Unique URL-safe slug using lowercase letters, numbers, and hyphens.
</ParamField>

<ParamField body="type" type="string">
  `business` or `personal`. Defaults to `business`.
</ParamField>

```bash theme={null}
curl -X POST "https://api.autosage.ai/api/v1/organizations" \
  -H "Cookie: YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc",
    "slug": "acme-inc",
    "type": "business"
  }'
```

<Tip>
  The creator becomes the `owner`. AutoSage also provisions a default environment, tenant, and starting credits; use [Current caller](/developers/api/users) to discover those resource IDs.
</Tip>

***

### Update an organization

`PATCH /organizations/:id`

Updates the organization's name or status. Requires an administrative role.

<ParamField path="id" type="string" required>
  The organization ID.
</ParamField>

<ParamField body="name" type="string">
  New display name.
</ParamField>

<ParamField body="status" type="string">
  New status — `active`, `inactive`, or `suspended`.
</ParamField>

<Warning>
  Only administrative roles (`owner`, `billing_admin`) may update an organization.
</Warning>

***

### Delete an organization

`DELETE /organizations/:id`

Permanently deletes the organization and everything under it.

<ParamField path="id" type="string" required>
  The organization ID.
</ParamField>

<Warning>
  Only the `owner` may delete an organization. This is irreversible and removes all environments, tenants, and content.
</Warning>

***

### List members

`GET /organizations/:id/members`

Returns the organization's active members (with their roles) and any pending invitations.

<ParamField path="id" type="string" required>
  The organization ID.
</ParamField>

```bash theme={null}
curl "https://api.autosage.ai/api/v1/organizations/ORG_ID/members" \
  -H "Cookie: YOUR_SESSION_COOKIE"
```

***

### Invite a member

`POST /organizations/:id/members`

Sends an invitation to an email address with an assigned role. The invitee accepts through the [invites](/developers/api/invites) flow.

<ParamField path="id" type="string" required>
  The organization ID.
</ParamField>

<ParamField body="email" type="string" required>
  Email address to invite.
</ParamField>

<ParamField body="role" type="string">
  Role to grant on acceptance — `billing_admin`, `developer`, or `viewer`. Defaults to `viewer`; ownership is assigned separately after the user joins.
</ParamField>

```bash theme={null}
curl -X POST "https://api.autosage.ai/api/v1/organizations/ORG_ID/members" \
  -H "Cookie: YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{ "email": "teammate@acme.com", "role": "developer" }'
```

<Note>
  Only the `owner` may invite members. Invitations expire after 7 days — see [Invites](/teams/invites).
</Note>

***

### Assign a role

`POST /organizations/:id/members/role`

Changes an existing member's role.

<ParamField path="id" type="string" required>
  The organization ID.
</ParamField>

<ParamField body="user_id" type="string" required>
  The member's user ID.
</ParamField>

<ParamField body="role" type="string" required>
  The new role — one of `owner`, `billing_admin`, `developer`, `viewer`.
</ParamField>

<Warning>
  Only the `owner` may change member roles.
</Warning>

***

### Remove a member

`DELETE /organizations/:id/members/:member_id`

Removes a member from the organization, revoking their access immediately.

<ParamField path="id" type="string" required>
  The organization ID.
</ParamField>

<ParamField path="member_id" type="string" required>
  The member's user ID.
</ParamField>

<Note>
  Only the `owner` may remove members.
</Note>

***

### Revoke an invite

`DELETE /organizations/:id/invites/:invite_id`

Cancels a pending invitation before it is accepted.

<ParamField path="id" type="string" required>
  The organization ID.
</ParamField>

<ParamField path="invite_id" type="string" required>
  The pending invitation ID.
</ParamField>

<Note>
  Only the `owner` may revoke invitations.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Members & roles" icon="users" href="/teams/members-roles">
    Understand exactly what each role can do.
  </Card>

  <Card title="Environments" icon="layer-group" href="/developers/api/environments">
    Add environments to isolate dev, staging, and production.
  </Card>

  <Card title="Invites" icon="envelope" href="/developers/api/invites">
    See how invitees accept and join.
  </Card>
</CardGroup>