Skip to main content

​
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

DomainAllowed Actions
CustomersCreate, read, delete
EntitiesCreate, read (by type / identifier), delete
AddressesCreate, delete
CatalogRead SKU groups, read/create SKUs
Billing PlansRead plan by ID, delete plan items
ContractsCreate, read, update; add/remove plan item milestones
InvoicesCreate, read, raise, send, mark paid, generate PDF, sync items, upload document
Invoice ItemsCreate, read, delete (draft invoices only)
PaymentsCreate, read, update, delete
RevenueCreate, read, sync by invoice item
UsageCreate, read, update, delete; bulk create/delete events
MetersRead, create usage by meter, sync all
EventsCreate, read by ID
JobsCreate, read, update, delete
Apps / CredentialsRead apps, read/update credentials
State Machine (FSM)Get states, get actions, transition, undo transition, create/read machines
Organisation SettingsRead, update
Org AttributesFull CRUD
Custom AttributesFull CRUD + validate
FX RatesCreate, read, update
GeoRead countries and states
CurrenciesRead
WebhooksTrigger webhooks
Objects QuerySchema lookup, query, export
ChatbotSend messages
EmailSend 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.