Admin API

This endpoint requires admin-level roles (platform_admin, tenant_admin, or system_admin). Accessible via the API gateway at /v1/platform/*.

Roles API

Manage roles and permissions for access control.

Overview

The Roles API provides flexible RBAC management:

Feature	Description
Role CRUD	Create, read, update, delete roles
Permissions	Granular permission management
Scoping	Tenant, location, or global scope
Inheritance	Role hierarchy support
Templates	Pre-built role templates

Role Model

{
  "id": "role-manager",
  "name": "Manager",
  "description": "Full location management access",
  "scope": "location",
  "type": "custom",
  "permissions": [
    "orders.*",
    "payments.*",
    "reports.read",
    "staff.read",
    "staff.write"
  ],
  "user_count": 12,
  "created_at": "2025-06-15T10:00:00Z"
}

Permission Structure

Permissions follow a resource.action pattern:

orders.read          - View orders
orders.write         - Create/edit orders
orders.delete        - Cancel/void orders
orders.refund        - Process refunds
orders.*             - All order permissions

Permission Categories

Category	Permissions
Orders	`orders.read`, `orders.write`, `orders.delete`, `orders.refund`, `orders.discount`
Payments	`payments.read`, `payments.write`, `payments.refund`, `payments.void`
Menu	`menu.read`, `menu.write`, `menu.delete`, `menu.pricing`
Inventory	`inventory.read`, `inventory.write`, `inventory.count`, `inventory.adjust`
Reports	`reports.read`, `reports.export`, `reports.financial`
Staff	`staff.read`, `staff.write`, `staff.delete`, `staff.schedule`
Settings	`settings.read`, `settings.write`, `settings.billing`
Admin	`admin.users`, `admin.roles`, `admin.locations`, `admin.integrations`

List Roles

Request

GET /api/v1/roles?tenant_id=tenant-abc123
Authorization: Bearer {access_token}

Query Parameters

Parameter	Type	Description
`tenant_id`	string	Filter by tenant
`scope`	string	Filter by scope
`type`	string	Filter by type (system, template, custom)
`include_permissions`	boolean	Include full permission list

Response

{
  "roles": [
    {
      "id": "role-owner",
      "name": "Owner",
      "description": "Full system access",
      "scope": "tenant",
      "type": "system",
      "user_count": 2,
      "is_system": true
    },
    {
      "id": "role-manager",
      "name": "Manager",
      "description": "Full location management",
      "scope": "location",
      "type": "template",
      "user_count": 5,
      "is_system": false
    },
    {
      "id": "role-server",
      "name": "Server",
      "description": "Order taking and payment",
      "scope": "location",
      "type": "template",
      "user_count": 25,
      "is_system": false
    }
  ]
}

Get Role

Request

GET /api/v1/roles/{role_id}
Authorization: Bearer {access_token}

Response

{
  "id": "role-manager",
  "name": "Manager",
  "description": "Full location management access",
  "scope": "location",
  "type": "template",
  "tenant_id": "tenant-abc123",
  "permissions": [
    "orders.read",
    "orders.write",
    "orders.delete",
    "orders.refund",
    "orders.discount",
    "payments.read",
    "payments.write",
    "payments.refund",
    "payments.void",
    "menu.read",
    "menu.write",
    "inventory.read",
    "inventory.write",
    "inventory.count",
    "reports.read",
    "reports.export",
    "staff.read",
    "staff.write",
    "staff.schedule",
    "settings.read"
  ],
  "inherits_from": null,
  "restrictions": {
    "max_discount_percent": 50,
    "max_refund_amount": 500,
    "require_manager_approval": false
  },
  "users": [
    {"id": "user-001", "name": "John Manager"},
    {"id": "user-002", "name": "Jane Manager"}
  ],
  "user_count": 5,
  "created_at": "2025-06-15T10:00:00Z",
  "updated_at": "2026-01-15T14:30:00Z"
}

Create Role

Request

POST /api/v1/roles
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "Shift Lead",
  "description": "Supervises shift operations",
  "scope": "location",
  "tenant_id": "tenant-abc123",
  "permissions": [
    "orders.read",
    "orders.write",
    "orders.discount",
    "payments.read",
    "payments.write",
    "staff.read",
    "reports.read"
  ],
  "restrictions": {
    "max_discount_percent": 20,
    "max_refund_amount": 100
  }
}

Parameters

Field	Type	Required	Description
`name`	string	Yes	Role name
`description`	string	No	Role description
`scope`	string	Yes	`tenant`, `location`, or `global`
`tenant_id`	string	Yes	Owning tenant
`permissions`	array	Yes	List of permissions
`inherits_from`	string	No	Parent role ID
`restrictions`	object	No	Role-specific limits

Response

{
  "id": "role-shiftlead",
  "name": "Shift Lead",
  "scope": "location",
  "permissions_count": 7,
  "created_at": "2026-01-18T12:00:00Z"
}

Update Role

Request

PATCH /api/v1/roles/{role_id}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "description": "Updated description",
  "restrictions": {
    "max_discount_percent": 25
  }
}

Update Permissions

Request

PUT /api/v1/roles/{role_id}/permissions
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "permissions": [
    "orders.read",
    "orders.write",
    "orders.discount",
    "orders.refund",
    "payments.read",
    "payments.write",
    "staff.read",
    "reports.read"
  ]
}

Add Permissions

Request

POST /api/v1/roles/{role_id}/permissions
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "permissions": ["inventory.read", "inventory.write"]
}

Remove Permissions

Request

DELETE /api/v1/roles/{role_id}/permissions
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "permissions": ["orders.refund"]
}

Role Templates

List Templates

GET /api/v1/roles/templates
Authorization: Bearer {access_token}

Response

{
  "templates": [
    {
      "id": "template-owner",
      "name": "Owner",
      "description": "Full access to all features",
      "scope": "tenant",
      "permissions_count": 45
    },
    {
      "id": "template-manager",
      "name": "Manager",
      "description": "Location management",
      "scope": "location",
      "permissions_count": 32
    },
    {
      "id": "template-server",
      "name": "Server",
      "description": "Order and payment processing",
      "scope": "location",
      "permissions_count": 12
    },
    {
      "id": "template-cashier",
      "name": "Cashier",
      "description": "Payment processing only",
      "scope": "location",
      "permissions_count": 8
    },
    {
      "id": "template-host",
      "name": "Host",
      "description": "Seating and reservations",
      "scope": "location",
      "permissions_count": 6
    },
    {
      "id": "template-kitchen",
      "name": "Kitchen Staff",
      "description": "KDS and order viewing",
      "scope": "location",
      "permissions_count": 5
    }
  ]
}

Create from Template

POST /api/v1/roles/from-template
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "template_id": "template-manager",
  "tenant_id": "tenant-abc123",
  "name": "Assistant Manager",
  "remove_permissions": ["staff.delete", "settings.write"],
  "add_permissions": []
}

Check Permissions

Request

POST /api/v1/roles/check
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "user_id": "user-abc123",
  "permissions": ["orders.refund", "payments.void"],
  "location_id": "loc-xyz789"
}

Response

{
  "user_id": "user-abc123",
  "results": {
    "orders.refund": true,
    "payments.void": false
  },
  "effective_roles": ["role-manager"]
}

List Available Permissions

Request

GET /api/v1/roles/permissions
Authorization: Bearer {access_token}

Response

{
  "permissions": [
    {
      "key": "orders.read",
      "name": "View Orders",
      "description": "View order details and history",
      "category": "Orders"
    },
    {
      "key": "orders.write",
      "name": "Create/Edit Orders",
      "description": "Create new orders and modify existing ones",
      "category": "Orders"
    },
    {
      "key": "orders.refund",
      "name": "Process Refunds",
      "description": "Issue refunds for orders",
      "category": "Orders",
      "requires": ["orders.read", "payments.read"]
    }
  ],
  "categories": [
    {"key": "orders", "name": "Orders"},
    {"key": "payments", "name": "Payments"},
    {"key": "menu", "name": "Menu"},
    {"key": "inventory", "name": "Inventory"},
    {"key": "reports", "name": "Reports"},
    {"key": "staff", "name": "Staff"},
    {"key": "settings", "name": "Settings"},
    {"key": "admin", "name": "Administration"}
  ]
}

Delete Role

Request

DELETE /api/v1/roles/{role_id}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "reassign_users_to": "role-server"
}

Response

{
  "id": "role-shiftlead",
  "deleted": true,
  "users_reassigned": 3
}

Role Hierarchy

Roles can inherit from other roles:

Owner (tenant scope)
├── Manager (location scope)
│   ├── Shift Lead
│   └── Assistant Manager
├── Server
│   └── Server Trainee
└── Kitchen Manager
    └── Line Cook

Set Inheritance

PUT /api/v1/roles/{role_id}/inheritance
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "inherits_from": "role-manager"
}

Error Responses

Role Not Found (404)

{
  "error": {
    "code": "ROLE_NOT_FOUND",
    "message": "Role does not exist"
  }
}

Cannot Delete System Role (403)

{
  "error": {
    "code": "SYSTEM_ROLE",
    "message": "Cannot delete or modify system roles"
  }
}

Invalid Permission (400)

{
  "error": {
    "code": "INVALID_PERMISSION",
    "message": "Permission 'invalid.permission' does not exist"
  }
}

Users API - User management
Gating API - Feature gating
Authentication - Auth flows

Overview​

Role Model​

Permission Structure​

Permission Categories​

List Roles​

Request​

Query Parameters​

Response​

Get Role​

Request​

Response​

Create Role​

Request​

Parameters​

Response​

Update Role​

Request​

Update Permissions​

Request​

Add Permissions​

Request​

Remove Permissions​

Request​

Role Templates​

List Templates​

Response​

Create from Template​

Check Permissions​

Request​

Response​

List Available Permissions​

Request​

Response​

Delete Role​

Request​

Response​

Role Hierarchy​

Set Inheritance​

Error Responses​

Role Not Found (404)​

Cannot Delete System Role (403)​

Invalid Permission (400)​

Related Documentation​

Overview

Role Model

Permission Structure

Permission Categories

List Roles

Request

Query Parameters

Response

Get Role

Request

Response

Create Role

Request

Parameters

Response

Update Role

Request

Update Permissions

Request

Add Permissions

Request

Remove Permissions

Request

Role Templates

List Templates

Response

Create from Template

Check Permissions

Request

Response

List Available Permissions

Request

Response

Delete Role

Request

Response

Role Hierarchy

Set Inheritance

Error Responses

Role Not Found (404)

Cannot Delete System Role (403)

Invalid Permission (400)

Related Documentation