Modules API

Register and list permission modules.

Modules represent functional areas of your application. They are used by the Full authorization model to define action sets that can be assigned to roles.

Scope: permissions:manage

Rate limit: 500/hr

List modules

GET /api/v1/permissions/modules

Returns all registered modules for the tenant.

curl https://api.platformxe.com/api/v1/permissions/modules \
  -H "x-api-key: pxk_live_your_api_key_here"

const modules = await px.permissions.listModules();

Response

{
  "success": true,
  "data": {
    "modules": [
      {
        "id": "mod_bookings",
        "name": "BOOKINGS",
        "description": "Booking management",
        "actions": ["READ", "CREATE", "UPDATE", "DELETE", "LIST", "APPROVE"],
        "createdAt": "2026-03-15T08:00:00.000Z"
      }
    ]
  }
}

Register a module

POST /api/v1/permissions/modules

Registration is durable — processed via a background job to ensure consistency across the system.

Field	Type	Required	Description
name	string	Yes	Module name (uppercase, e.g., BOOKINGS)
description	string	No	Human-readable description
actions	string[]	Yes	Supported actions for this module

curl -X POST https://api.platformxe.com/api/v1/permissions/modules \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "name": "PROPERTIES",
    "description": "Property listing management",
    "actions": ["READ", "CREATE", "UPDATE", "DELETE", "LIST", "PUBLISH"]
  }'

await px.permissions.registerModule({
  name: 'PROPERTIES',
  description: 'Property listing management',
  actions: ['READ', 'CREATE', 'UPDATE', 'DELETE', 'LIST', 'PUBLISH'],
});

Module limits by plan

Plan	Max modules
Free	5
Basic	20
Pro	50
Enterprise	Unlimited

Attempting to register a module beyond your plan limit returns a BILLING_LIMIT error.

Error responses

Code	Description
BAD_REQUEST	Missing name or empty actions array
BILLING_LIMIT	Module count exceeds plan limit
FORBIDDEN	API key missing permissions:manage scope