# Organisation endpoints

> List the Vigilbase One organisations you belong to, the members of your current organisation and the roles you can assign, over the One API.

Source: https://docs.vigilbase.com/one/api/organizations

These endpoints read organisation context. None of them changes which organisation your token belongs to: to switch, sign in again and choose another one. None has a v1 operation yet: they are on `https://one.vigilbase.com`. Sign-in, permissions and error shapes are on [Vigilbase One API](https://docs.vigilbase.com/one/api).

| Method and path | Permission | CLI command |
| --- | --- | --- |
| `GET /api/user/organizations` | Any signed-in user | `vigilbase orgs list` |
| `GET /api/auth/orgs/members` | `read:organizations` | `vigilbase orgs members` |
| `GET /api/auth/orgs/permission-roles` | Organisation managers | `vigilbase orgs roles` |

Paths under `/api/auth/orgs/` allow 20 requests a minute per IP address. These endpoints answer without a `success` field, and most of their errors are `{ "error": "…" }`.

## Your organisations

`GET /api/user/organizations` lists every organisation you belong to:

```json
{
  "organizations": [
    { "id": "…", "name": "example", "displayName": "Example Ltd", "logoUrl": "…", "metadata": { } }
  ]
}
```

`name` is the organisation's short name (slug) and `displayName` the name people see.

## Members

`GET /api/auth/orgs/members` lists the members of the token's organisation:

| Field | Contents |
| --- | --- |
| `userId`, `email`, `name` | The member |
| `roles` | The member's role in One |
| `hasRoleVigilApproval` | Whether the member's role lets them approve Vigil actions |
| `permissions`, `customPermissions` | The member's permission settings; `null` unless you have `manage:organizations` |

Every customer role has `read:organizations`, so any member can list members.

## Assignable roles

`GET /api/auth/orgs/permission-roles` returns the role templates you can assign, the permission groups and a label for each permission:

```json
{ "roles": [ … ], "permissionGroups": [ … ], "permissionLabels": { "read:billing": "…" } }
```

Only people who manage the organisation, such as owners and admins, can call it; others get `403`. The list leaves out roles and permissions you couldn't grant yourself, and shows the owner role only to owners. It doesn't list each member's role; use [members](#members) for that.

## Invitations need the browser

`GET /api/auth/orgs/invitations` and `POST /api/auth/orgs/invite` work only from a One browser session. With a CLI token, an organisation manager gets `403` with `"code": "browser_session_required"`, and no invitation is sent. Invite and manage members on the [Organization](https://one.vigilbase.com/organization) page instead; see [Members and roles](https://docs.vigilbase.com/one/getting-started/members-and-roles#invite-a-member).