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

# Organizations & Access Control

> Manage teams, roles, and usage limits across your organization.

Mesh API organizes everything under a tenant hierarchy so teams can share billing, set usage limits, and control who can do what. You manage all of this from the [Dashboard](https://app.meshapi.ai).

## The hierarchy

```
Organization
  └── Team
       └── Members
```

| Level            | What it is                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------ |
| **Organization** | The top-level account. Holds billing, members, and teams.                                  |
| **Team**         | A group within the organization with its own members, API keys, and usage limits.          |
| **Member**       | An individual person who belongs to the organization, and optionally to one or more teams. |

Each user belongs to **one organization at a time**. To join a different organization, you leave your current one when accepting the new invitation.

## Roles

### Organization roles

| Role       | Capabilities                                                                                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Owner**  | Full administrative control over the organization. There is exactly one owner per organization.                                                                    |
| **Admin**  | Edit organization settings and limits, create and delete teams, invite and remove members, change member roles and limits, and view all members, usage, and spend. |
| **Member** | Use the API and view their own usage. Members cannot manage other members, teams, or settings.                                                                     |

### Team roles

| Role       | Capabilities                                           |
| ---------- | ------------------------------------------------------ |
| **Admin**  | Manage the team's members, API keys, and usage limits. |
| **Member** | Use the team's API keys to make requests.              |

<Info>
  Organization owners and admins automatically have admin access to every team in the organization.
</Info>

## Inviting members

<Steps>
  <Step title="Send an invitation">
    An organization owner or admin invites a teammate by email from the Dashboard, choosing their role (admin or member) and, optionally, a team to add them to.
  </Step>

  <Step title="The invitee accepts">
    The invited person receives an email with a link. After signing in with the invited email address, they accept the invitation to join the organization with the assigned role.
  </Step>

  <Step title="Manage pending invitations">
    Admins can view, resend, or revoke pending invitations from the Dashboard. Invitations expire automatically after 72 hours.
  </Step>
</Steps>

## Usage limits & spend caps

Limits can be set at four scopes. Each scope supports the same set of controls:

| Control       | Description         |
| ------------- | ------------------- |
| **RPM**       | Requests per minute |
| **RPD**       | Requests per day    |
| **TPM**       | Tokens per minute   |
| **Spend cap** | Maximum USD spend   |

The four scopes:

| Scope            | Applies to                                                                 |
| ---------------- | -------------------------------------------------------------------------- |
| **Organization** | All usage across the entire organization                                   |
| **Team**         | All usage under a team                                                     |
| **Member**       | An individual member's usage                                               |
| **API key**      | A single key (see [Dashboard → API Keys](/docs/getting-started/dashboard)) |

A request must satisfy **every** limit that applies to it — across the key, the member, the team, and the organization. If any one of them is exceeded, the request is rejected. Any scope left unset has no limit at that level.

<Info>
  Spend caps at the organization, team, and member levels are evaluated over a rolling 30-day window.
</Info>

## When a limit is hit

| Condition                       | HTTP status             | Error code             |
| ------------------------------- | ----------------------- | ---------------------- |
| RPM, RPD, or TPM limit exceeded | `429 Too Many Requests` | `rate_limit_exceeded`  |
| Spend cap reached               | `402 Payment Required`  | `spend_limit_exceeded` |

Rate-limit responses include a `Retry-After` header indicating how long to wait before retrying. If a member or organization spend cap is reached, contact your organization admin to raise it.

***

## Managing orgs through the API

<Note>
  Org management uses a **user JWT** — your dashboard session token — not an `rsk_` key.
</Note>

### The `/current` model

Every org endpoint is scoped to `/current` — the org identified by your session token. There is **no `{org_id}` path parameter anywhere in the API**:

| Operation                | Endpoint                                              |
| ------------------------ | ----------------------------------------------------- |
| Create an org            | `POST /v1/orgs`                                       |
| Get your org             | `GET /v1/orgs/current`                                |
| Invite a member          | `POST /v1/orgs/current/members`                       |
| List members             | `GET /v1/orgs/current/members`                        |
| List pending invitations | `GET /v1/orgs/current/invitations`                    |
| Resend an invitation     | `POST /v1/orgs/current/invitations/{inv_id}/resend`   |
| Create a team            | `POST /v1/orgs/current/teams`                         |
| List teams               | `GET /v1/orgs/current/teams`                          |
| Team members             | `GET`/`POST /v1/orgs/current/teams/{team_id}/members` |
| Org usage                | `GET /v1/orgs/current/usage`                          |
| Spend by member          | `GET /v1/orgs/current/spend`                          |
| Transfer ownership       | `POST /v1/orgs/current/transfer-ownership`            |
| Leave the org            | `POST /v1/orgs/current/leave`                         |

<Warning>
  Because the target org comes from your **token**, a stale token silently acts on the wrong org rather than erroring. If you belong to more than one org, re-authenticate after switching rather than reusing a cached token.
</Warning>

### Inviting people

Creating a member *is* creating an invitation — `POST /v1/orgs/current/members` returns an invitation record, and the person joins when they accept it.

```bash theme={null}
curl https://api.meshapi.ai/v1/orgs/current/members \
  -H "Authorization: Bearer <YOUR_USER_JWT>" \
  -H "Content-Type: application/json" \
  -d '{ "email": "teammate@example.com", "role": "member" }'
```

The invitee accepts through `/v1/invitations` — they can validate a token, list invitations addressed to them, and accept one.

<Note>
  You cannot assign `owner` through an invitation, and you cannot change someone into an owner with a role update — ownership moves only through `POST /v1/orgs/current/transfer-ownership`. Attempting either returns `422`.
</Note>

***

## Shared billing

<Warning>
  **Every member of an org spends from one balance — the owner's.** There is no per-member wallet. A single member with an uncapped key can consume the entire organization's credit.

  Per-member spend caps are the control for this, and they are **unlimited by default**. Set them deliberately; see [Rate Limits & Spend Caps](/docs/getting-started/rate-limits).
</Warning>

`GET /v1/orgs/current/spend` breaks spend down by member, which is the fastest way to find out where the balance went.

## Pooled limits

Limits set at org, team, and member level combine with the key's own limits, and **the smallest applicable value wins**. Raising a key's limit does nothing if the team above it is lower.

`GET /v1/keys/{id}/limits` shows the resolved result and which tier is binding — see [Rate Limits & Spend Caps](/docs/getting-started/rate-limits).

## Audit log

Every governance action in your org — key created, member invited, role changed, limit updated — is recorded in an append-only audit trail.

```bash theme={null}
curl "https://api.meshapi.ai/v1/audit-logs?limit=50" \
  -H "Authorization: Bearer <YOUR_USER_JWT>"
```

| Parameter                   | Notes                                    |
| --------------------------- | ---------------------------------------- |
| `limit`                     | Page size                                |
| `cursor`                    | Pagination cursor from the previous page |
| `action`                    | Filter by action type                    |
| `target_type` / `target_id` | Filter by what was acted on              |
| `actor_id`                  | Filter by who acted                      |
| `q`                         | Free-text search                         |
| `from` / `to`               | Time window                              |

`GET /v1/audit-logs.csv` returns the same filtered trail as a CSV download for compliance reviews.

## Related

* [API Keys](/docs/getting-started/api-keys) — attaching keys to an org or team
* [Rate Limits & Spend Caps](/docs/getting-started/rate-limits) — how pooled limits resolve
* [Usage & Monitoring API](/docs/reference/usage-api) — org-level usage and spend