Accounts

Overview

Bearer tokens are tied to a user, not a single organisation. The accounts routes let an authenticated user read or update one of their organisations:

Both routes require a valid bearer token. See Authentication.

Organisation selection

When a user belongs to exactly one organisation, organisationId is optional — the API resolves the sole membership automatically.

When a user belongs to more than one organisation, organisationId is required. Omitting it returns 400:

{ "error": "You belong to multiple organisations; specify organisationId" }

The API always validates that the caller is a member of the requested organisation. A foreign organisationId returns 404.

GET example

GET /api/v1/accounts?organisationId=clorg123abc HTTP/1.1
Host: hgvtraders.com
Authorization: Bearer <token>

{
  "data": {
    "id": "clorg123abc",
    "name": "Acme Trucks Ltd",
    "slug": "acme-trucks",
    "phone": "+441234567890",
    "website": "https://acmetrucks.co.uk",
    "role": "ADMIN"
  }
}

The role field reflects the caller's membership role on that organisation.

Updating an organisation

PATCH /api/v1/accounts requires ADMIN role on the target organisation. Updatable fields: name, phone, website.

PATCH /api/v1/accounts HTTP/1.1
Host: hgvtraders.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "organisationId": "clorg123abc",
  "name": "Acme Trucks Ltd",
  "phone": "+441234567890"
}

Multi-org integrations

If your integration acts on behalf of a user who may belong to multiple dealerships:

1. Resolve the target organisationId in your own configuration, or
2. Use dashboard org-switching and mint tokens per workflow as appropriate.

The bearer token alone does not imply which organisation is active.