System User Permissions

Overview

The System User role is designed for machine-to-machine API integrations. When you create API keys and authenticate via POST /auth/system-login, your requests run under this role. System Users have a focused permission set covering the core O2C (order-to-cash) lifecycle — they can ingest data, manage contracts, trigger invoicing, and read financial records, but they cannot perform destructive administrative operations (e.g. deleting plans, managing other users, or purging organisations).

Permission Summary by Domain

Domain	Allowed Actions
Customers	Create, read, delete
Entities	Create, read (by type / identifier), delete
Addresses	Create, delete
Catalog	Read SKU groups, read/create SKUs
Billing Plans	Read plan by ID, delete plan items
Contracts	Create, read, update; add/remove plan item milestones
Invoices	Create, read, raise, send, mark paid, generate PDF, sync items, upload document
Invoice Items	Create, read, delete (draft invoices only)
Payments	Create, read, update, delete
Revenue	Create, read, sync by invoice item
Usage	Create, read, update, delete; bulk create/delete events
Meters	Read, create usage by meter, sync all
Events	Create, read by ID
Jobs	Create, read, update, delete
Apps / Credentials	Read apps, read/update credentials
State Machine (FSM)	Get states, get actions, transition, undo transition, create/read machines
Organisation Settings	Read, update
Org Attributes	Full CRUD
Custom Attributes	Full CRUD + validate
FX Rates	Create, read, update
Geo	Read countries and states
Currencies	Read
Webhooks	Trigger webhooks
Objects Query	Schema lookup, query, export
Chatbot	Send messages
Email	Send email

What System Users CANNOT Do

Create, update, or delete billing plans (full plan management)
Create, update, or delete users, including other system users
Create or delete SKU groups
Delete customers (only supported via AdminAccess for safety)
Manage invoice templates
Manage email templates
Manage workflows, schedules, or filters
Access organisation/user administration features

Authenticating as a System User

Step 1 — Generate credentials (Admin UI or API):

POST /users/system
Authorization: Bearer <admin-token>

Response includes clientKey and clientSecret. Step 2 — Exchange for a JWT:

POST /auth/system-login
Content-Type: application/json

{
  "clientKey": "ck_live_abc123",
  "clientSecret": "cs_live_xyz789"
}

Response:

{
  "status": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Step 3 — Use the token:

GET /customers
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Tokens expire after a short TTL. Use POST /auth/refresh with your refreshToken to obtain a new access token without re-authenticating.

Permission Errors

If a System User calls an endpoint that requires a policy action they don’t have, the API returns:

{
  "status": "error",
  "message": "Forbidden",
  "errors": []
}

HTTP 403 — Insufficient policy permissions. Each endpoint in this reference includes a SystemUser accessible note listing the required policy actions.

​Overview

​Permission Summary by Domain

​What System Users CANNOT Do

​Authenticating as a System User

​Permission Errors

Overview

Permission Summary by Domain

What System Users CANNOT Do

Authenticating as a System User

Permission Errors