# Organizations, members & roles

> https://docs.errora.org/en/account/organizations

An **organization** owns projects, members, integrations, channels, dashboards, a wallet and
a retention policy. Every user gets a **personal organization** on signup and can create or
join more.

## Create an organization

**Organization switcher (top of the sidebar) → New organization.** You become its `owner`.

```text
GET/POST /api/v1/organizations
```

## Invite people

Invites go out by **SMS** to an Iranian mobile number — that is the login identifier.

1. **Settings → Members → Invite**.
2. Enter the mobile number and choose a role.
3. The invitee gets an SMS with a link; opening it and signing in joins them to the
   organization.

```bash
curl -X POST "$ERRORA/api/v1/organizations/$ORG_ID/invite" \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"phone":"09121234567","role":"member"}'
```

An invite is `pending` until accepted and expires after its window closes; re-invite to issue
a fresh one.

```text
GET   /api/v1/organizations/{id}/members
PATCH /api/v1/organizations/{id}/members/{member_id}     # change a role
GET   /api/v1/organizations/{id}/invites
POST  /api/v1/organizations/{id}/invite
GET   /api/v1/invites/preview/{token}
POST  /api/v1/invites/accept
```

## Roles & permissions

Five roles, applied **per organization** and optionally **per project** (a project-level role
overrides the organization one for that project):

| Role | Meant for |
| --- | --- |
| `owner` | Full control, including deleting the organization |
| `admin` | Everything except ownership-level actions |
| `member` | Day-to-day work: triage issues, trigger auto-fix |
| `billing` | Wallet, usage and payments — no engineering access |
| `viewer` | Read-only |

Roles resolve through a **capability matrix**, and every endpoint checks a capability rather
than a role name:

| Capability | Allows |
| --- | --- |
| `org:manage` | Rename/delete the organization, manage members and roles |
| `org:billing` | View and change billing, see usage and payments |
| `project:create` | Create projects |
| `project:manage` | Project settings, DSN keys, delete |
| `project:read` | View issues, events, logs, dashboards |
| `issue:write` | Resolve / ignore / assign / comment, submit user reports |
| `ai:trigger` | Start AI auto-fix runs |
| `integration:manage` | Connect and sync source-control integrations |
| `webhook:manage` | Manage notification channels and alert rules |

### Per-project roles

Give a contractor `viewer` at the organization level and `member` on the one project they
work on. The project role wins for that project.

## Organization settings

**Settings → Organization**: name, slug, and
[data retention](/en/account/retention). Deleting an organization deletes its projects and
all their data — there is no undo.

### Enforce two-factor authentication

Owners and admins can require [2FA](/en/account/auth) for the whole organization. While it is
on, a member without TOTP enrolled is refused every request for this organization's data
(`403 2fa_required`) and the dashboard sends them to their profile to enrol; their other
organizations are unaffected.

You can only turn it on once your own account has 2FA — otherwise the switch would lock you
out of the organization you just secured. The members tab marks anyone who has yet to enrol.

## Troubleshooting

| Symptom | Cause / fix |
| --- | --- |
| Invite SMS never arrives | The number isn't a valid `09…` Iranian mobile, or the SMS is delayed — re-send the invite after a minute |
| Invitee lands in the wrong organization | They accepted a different pending invite — check **Invites** |
| `403` on an action | The role lacks the capability; check the matrix above rather than guessing |
| Can't remove the last owner | An organization must keep at least one owner — promote someone first |