Documentation

Organization Routes

These pages document the live organization endpoints mounted under /api/organizations.

`GET /api/organizations/me`

Returns the current organization summary for the authenticated user.

Request
GET /api/organizations/me
Authorization: Bearer <access-token>

Response 200
{
  "organization": {
    "id": "uuid",
    "name": "Current Org",
    "criticalStockThreshold": 10,
    "lowStockThreshold": 25
  }
}

`GET /api/organizations/me/members`

Lists members in the authenticated user's current organization.

Request
GET /api/organizations/me/members
Authorization: Bearer <access-token>

Response 200
{
  "members": [
    {
      "accountId": "uuid",
      "orgId": "uuid",
      "email": "[email protected]",
      "username": "owner_user",
      "name": "Owner",
      "profileUrl": null,
      "authProvider": "cognito",
      "cognitoSub": "sub-123",
      "roleId": "uuid",
      "roleName": "owner",
      "createdAt": "2026-03-28T00:00:00.000Z",
      "updatedAt": "2026-03-29T12:00:00.000Z"
    }
  ]
}

`GET /api/organizations/me/members/count`

Returns the current organization and the number of members in it.

Request
GET /api/organizations/me/members/count
Authorization: Bearer <access-token>

Response 200
{
  "organization": {
    "id": "uuid",
    "name": "Current Org",
    "criticalStockThreshold": 10,
    "lowStockThreshold": 25
  },
  "memberCount": 2
}

`GET /api/organizations/me/roles`

Lists roles in the authenticated user's current organization.

Request
GET /api/organizations/me/roles

Response 200
{
  "roles": [
    {
      "id": "uuid",
      "orgId": "uuid",
      "name": "manager",
      "createdAt": "2026-04-01T00:00:00.000Z",
      "permissions": [
        "organization:members:read",
        "inventory:read"
      ]
    }
  ]
}

`GET /api/organizations/me/permissions`

Returns the assignable permission catalog for role-management screens.

Request
GET /api/organizations/me/permissions

Response 200
{
  "permissions": [
    {
      "id": 101,
      "key": "organization:read"
    }
  ],
  "permissionMap": {
    "organization:read": 101
  }
}

`POST /api/organizations/me/roles`

Creates a custom role in the current organization.

Request
POST /api/organizations/me/roles
Content-Type: application/json

{
  "name": "auditor",
  "permissions": [
    "organization:read",
    "inventory:read"
  ]
}

Response 201
{
  "role": {
    "id": "uuid",
    "orgId": "uuid",
    "name": "auditor",
    "createdAt": "2026-04-04T00:00:00.000Z",
    "permissions": [
      "organization:read",
      "inventory:read"
    ]
  }
}

`PATCH /api/organizations/me/members/:accountId`

Updates the role assignment for a member in the current organization.

Request
PATCH /api/organizations/me/members/11111111-1111-1111-1111-111111111111
Content-Type: application/json

{
  "roleId": "22222222-2222-2222-2222-222222222222"
}

Response 200
{
  "member": {
    "accountId": "uuid",
    "orgId": "uuid",
    "email": "[email protected]",
    "username": "member_user",
    "name": "Member",
    "profileUrl": null,
    "authProvider": "cognito",
    "cognitoSub": "sub-123",
    "roleId": "uuid",
    "roleName": "auditor",
    "createdAt": "2026-03-28T00:00:00.000Z",
    "updatedAt": "2026-04-04T00:00:00.000Z"
  }
}

`POST /api/organizations`

Creates a new organization, creates the owner role, and switches the current account into the new organization.

Request
POST /api/organizations
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "name": "Acme Warehouse"
}

Response 201
{
  "organization": {
    "id": "uuid",
    "name": "Acme Warehouse"
  }
}

`PATCH /api/organizations/:organizationId`

Updates the authenticated user's current organization if the caller has the required org permission.

Request
PATCH /api/organizations/9e4a6f64-1111-2222-3333-444444444444
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "name": "Acme Warehouse SG",
  "criticalStockThreshold": 5,
  "lowStockThreshold": 15
}

Response 200
{
  "organization": {
    "id": "9e4a6f64-1111-2222-3333-444444444444",
    "name": "Acme Warehouse SG",
    "criticalStockThreshold": 5,
    "lowStockThreshold": 15
  }
}

`DELETE /api/organizations/:organizationId`

Deletes the authenticated user's current organization if allowed. Deletion can be blocked by existing related records.

Request
DELETE /api/organizations/9e4a6f64-1111-2222-3333-444444444444
Authorization: Bearer <access-token>

Response 200
{
  "organization": {
    "id": "9e4a6f64-1111-2222-3333-444444444444",
    "name": "Acme Warehouse SG"
  }
}