Directory endpoints

All endpoints in this section require both headers:

Authorization: Bearer <app-signed-user-access-token>
X-App-Public-Key: <app-public-key>

The user's company is taken from the bearer token's company_id claim.

Get the current company

GET /api/v1/external/company

Response:

{
  "id": "company-uuid",
  "name": "Acme Company",
  "slug": "acme-company",
  "status": "ACTIVE"
}

Get all users in the company

Use this when an external app needs the company's user directory.

GET /api/v1/external/users?page=0&size=50&search=member

Returns active company memberships. Each user includes current account status and active category assignments. Response item shape:

{
  "id": "membership-uuid",
  "userId": "user-uuid",
  "email": "member@example.com",
  "name": "Company Member",
  "systemRole": "USER",
  "userStatus": "ACTIVE",
  "role": "MEMBER",
  "membershipStatus": "ACTIVE",
  "categories": [
    {
      "id": "category-uuid",
      "companyId": "company-uuid",
      "name": "Finance",
      "slug": "finance",
      "description": "Finance team",
      "status": "ACTIVE"
    }
  ]
}

Get all company categories

GET /api/v1/external/categories?page=0&size=50&search=finance

Response item shape:

{
  "id": "category-uuid",
  "companyId": "company-uuid",
  "name": "Finance",
  "slug": "finance",
  "description": "Finance team",
  "status": "ACTIVE"
}

Get users assigned to a category

Use the category UUID returned by /api/v1/external/categories.

GET /api/v1/external/categories/{categoryId}/users?page=0&size=50

Rules:

• categoryId must belong to the company resolved from the bearer token.
• The response includes active company memberships assigned to that category.
• The item shape is the same as /api/v1/external/users.

Get applications accessible to the company

GET /api/v1/external/applications?page=0&size=50&search=portal

Response item shape:

{
  "id": "company-application-or-application-uuid",
  "companyId": "company-uuid",
  "companyName": "Acme Company",
  "applicationId": "application-uuid",
  "applicationName": "Spend Portal",
  "appId": "spend-portal",
  "status": "ACTIVE",
  "startsAt": null,
  "expiresAt": null,
  "allCompany": false,
  "categories": [
    {
      "id": "category-uuid",
      "companyId": "company-uuid",
      "name": "Finance",
      "slug": "finance",
      "status": "ACTIVE"
    }
  ]
}

Access meaning:

• allCompany: true — every active company member can access the app.
• allCompany: false with categories — only users assigned to at least one listed category can access the app.

Get users who can access a specific application

Use the applicationId returned by /api/v1/external/applications.

GET /api/v1/external/applications/{applicationId}/users?page=0&size=50

Rules:

• All-company access returns the company's active users.
• Category access returns active users assigned to at least one active app category.
• Disabled applications return no users.
• The item shape is the same as /api/v1/external/users.

Current-user app endpoint

External apps can also use the current-user dashboard endpoint when they only need the authenticated user's apps:

GET /api/v1/me/apps

Response:

[
  {
    "companyId": "company-uuid",
    "companyName": "Acme Company",
    "applications": [
      {
        "id": "application-uuid",
        "name": "Spend Portal",
        "appId": "spend-portal",
        "description": "Spend management",
        "status": "ACTIVE"
      }
    ]
  }
]