Organisation API¶

Manage organisations and their members. All endpoints require authentication and appropriate role permissions.

Create Organisation¶

POST /api/organisations¶

Create a new organisation. The authenticated user becomes the Owner.

Request:

Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "BHP Coal",
  "slug": "bhp",
  "timezone": "Australia/Brisbane"
}

Response (201):

{
  "id": "d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
  "name": "BHP Coal",
  "slug": "bhp",
  "timezone": "Australia/Brisbane",
  "createdAt": "2026-02-18T10:00:00Z"
}

List Organisations¶

GET /api/organisations¶

List all organisations the authenticated user belongs to.

Response (200):

{
  "data": [
    {
      "id": "d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
      "name": "BHP Coal",
      "slug": "bhp",
      "role": "admin"
    },
    {
      "id": "e5f6a7b8-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
      "name": "Deftec",
      "slug": "deftec",
      "role": "engineer"
    }
  ]
}

Get Organisation¶

GET /api/organisations/{id}¶

Response (200):

{
  "id": "d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
  "name": "BHP Coal",
  "slug": "bhp",
  "timezone": "Australia/Brisbane",
  "memberCount": 24,
  "siteCount": 3,
  "createdAt": "2026-02-18T10:00:00Z"
}

Update Organisation¶

PUT /api/organisations/{id}¶

Requires Admin or Owner role.

Request:

{
  "name": "BHP Coal Operations",
  "timezone": "Australia/Brisbane"
}

Members¶

GET /api/organisations/{id}/members¶

List all members of the organisation.

Response (200):

{
  "data": [
    {
      "userId": "a3f1c9e0-7b2d-4e8a-b5f6-1d2e3f4a5b6c",
      "email": "admin@bhp.com",
      "firstName": "Jane",
      "lastName": "Smith",
      "role": "owner",
      "joinedAt": "2026-02-18T10:00:00Z"
    }
  ]
}

POST /api/organisations/{id}/members¶

Invite a user to the organisation. If the user doesn't have an account, an invitation email is sent. Requires Admin or Owner role.

Request:

{
  "email": "operator@bhp.com",
  "role": "operator"
}

Response (201):

{
  "userId": "b4c5d6e7-8f9a-0b1c-2d3e-4f5a6b7c8d9e",
  "email": "operator@bhp.com",
  "role": "operator",
  "status": "invited"
}

PUT /api/organisations/{id}/members/{userId}¶

Update a member's role. Requires Admin or Owner role.

Request:

{
  "role": "engineer"
}

DELETE /api/organisations/{id}/members/{userId}¶

Remove a member from the organisation. Requires Admin or Owner role.

Domain Configuration¶

GET /api/organisations/{id}/domains¶

List email domains configured for auto-join.

POST /api/organisations/{id}/domains¶

Associate an email domain with the organisation. Users with matching email addresses are automatically offered membership on sign-up. Requires Admin or Owner role.

Request:

{
  "domain": "bhp.com"
}

DELETE /api/organisations/{id}/domains/{domain}¶

Remove a domain association.