> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getenso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# System User Permissions

> Complete reference of what a System User (API integration role) can access in the Enso API.

## 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):

```http theme={null}
POST /users/system
Authorization: Bearer <admin-token>
```

Response includes `clientKey` and `clientSecret`.

**Step 2 — Exchange for a JWT**:

```http theme={null}
POST /auth/system-login
Content-Type: application/json

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

Response:

```json theme={null}
{
  "status": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

**Step 3 — Use the token**:

```http theme={null}
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:

```json theme={null}
{
  "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.