Authentication — Maya Wealth Group Documentation

Authenticated APIs use HS256 bearer JWTs. All rows are scoped to orgId.

Send the token on every private request:

curl -sS \
  -X GET \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/"

Claims:

Claim	Meaning
`orgId`	Organisation / tenant id
`actorId`	Acting user or device id
`actorType`	Optional. Present on some development tokens and Signage device tokens. Directory login omits it

Directory login tokens contain only orgId and actorId. Each domain Worker resolves the caller's user type from Directory service_memberships (GET /v1/memberships?service=...).

Fine-grained permissions come from that user type (built into code) and, where supported, custom access roles stored in the service database.

Shared user types

Every Directory-backed API uses the same four built-in user types. These are access levels, not job titles:

User type	Typical use
`admin`	Full service administration
`area-manager`	Multi-site operational oversight
`manager`	Team and day-to-day operational management
`member`	Standard self-service access

Directory assigns a user type per service in service_memberships. The same person may be admin in HR and member in Venue.

Custom role slugs are also allowed. Services may define extra permissions in access_roles (or Venue /v1/roles). Built-in user types are not stored in D1 — they are returned from code via GET /v1/access-roles alongside custom rows.

Signage devices

Signage operators use the same four user types. Raspberry Pi players use a separate actor type:

Actor	Meaning
`display_device`	Device runtime token (`actorId` is the device id; not a Directory person)

Public routes

These do not require a JWT:

GET /health
GET /doc
GET /docs
Login / register / device enrol routes documented on each service

First-time setup

Create the organisation in Directory (POST /v1/auth/register or PUT /v1/organisation), assign service_memberships, then project people and locations with POST /v1/directory/ingest on each domain Worker.

curl -sS \
  -X PUT \
  "https://api.mayawealth.co.uk/v1/organisation"

Venue and HR can also apply service-specific settings (HR legal name/timezone/currency, Venue brands). See the service pages for the exact bootstrap flow.