Permissions API

Permission endpoints require a Bearer token with the appropriate permission. All endpoints are scoped to the tenant identified by the X-Tenant-ID header.

Permission convention: permission:read grants list/get access. permission:write grants create/update/delete access.

Base path: https://api.ithbat.io/api/v1/

---

Permissions

Permissions are fine-grained authorization tokens in the format resource:action. System permissions are built-in and cannot be modified. Custom permissions let tenant admins extend the authorization model for their own applications.

GET /api/v1/permissions

Permission: permission:read

List all permissions available in the tenant, including both system and custom permissions.

curl "https://api.ithbat.io/api/v1/permissions" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>"

Response 200

{
  "success": true,
  "data": {
    "permissions": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
        "name": "report:read",
        "displayName": "View Reports",
        "description": "Allows reading analytics and usage reports",
        "category": "Analytics",
        "isSystem": false,
        "createdAt": "2026-02-10T08:30:00Z"
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
        "name": "user:read",
        "displayName": "View Users",
        "description": "Allows listing and viewing user profiles",
        "category": "User Management",
        "isSystem": true,
        "createdAt": "2025-11-01T00:00:00Z"
      }
    ],
    "total": 2
  }
}

GET /api/v1/permissions/categories

Permission: permission:read

List all distinct permission categories used in the tenant. Useful for grouping permissions in UI consent and role-builder screens.

curl "https://api.ithbat.io/api/v1/permissions/categories" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>"

Response 200

{
  "success": true,
  "data": {
    "categories": [
      "Analytics",
      "Audit",
      "Billing",
      "Directory",
      "Identity",
      "OAuth",
      "Organization",
      "Policy",
      "User Management",
      "Webhooks"
    ]
  }
}

GET /api/v1/permissions/{id}

Permission: permission:read

Get a single permission by its ID.

curl "https://api.ithbat.io/api/v1/permissions/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>"

Response 200

{
  "success": true,
  "data": {
    "permission": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
      "name": "report:read",
      "displayName": "View Reports",
      "description": "Allows reading analytics and usage reports",
      "category": "Analytics",
      "isSystem": false,
      "createdAt": "2026-02-10T08:30:00Z"
    }
  }
}

POST /api/v1/permissions

Permission: permission:write

Create a custom permission. The name must follow the resource:action format and must be unique within the tenant. System permission names (those already registered by Ithbat IAM) are reserved and will be rejected.

Request Body

Field	Type	Required	Description
name	string	Yes	Permission identifier in resource:action format (e.g. report:export)
displayName	string	Yes	Human-readable label shown in the admin console and consent screens
description	string	No	Longer explanation of what this permission grants
category	string	No	Grouping label used in the admin console (e.g. Analytics)

curl -X POST "https://api.ithbat.io/api/v1/permissions" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "report:export",
    "displayName": "Export Reports",
    "description": "Allows exporting analytics reports to CSV or PDF",
    "category": "Analytics"
  }'

Response 201

{
  "success": true,
  "data": {
    "permission": {
      "id": "c3d4e5f6-a7b8-9012-cdef-012345678902",
      "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
      "name": "report:export",
      "displayName": "Export Reports",
      "description": "Allows exporting analytics reports to CSV or PDF",
      "category": "Analytics",
      "isSystem": false,
      "createdAt": "2026-03-19T11:45:00Z"
    }
  }
}

PUT /api/v1/permissions/{id}

Permission: permission:write

Update a custom permission's display name, description, or category. The name field (the resource:action identifier) cannot be changed after creation. System permissions cannot be modified.

Request Body — All fields optional:

Field	Type	Description
displayName	string	Updated human-readable label
description	string	Updated description
category	string	Updated category grouping

curl -X PUT "https://api.ithbat.io/api/v1/permissions/c3d4e5f6-a7b8-9012-cdef-012345678902" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Export Reports (CSV & PDF)",
    "description": "Allows exporting analytics reports to CSV or PDF format",
    "category": "Analytics"
  }'

Response 200 — Returns the updated PermissionResponse.

DELETE /api/v1/permissions/{id}

Permission: permission:write

Delete a custom permission. System permissions cannot be deleted. Deleting a permission automatically removes it from all roles that reference it.

curl -X DELETE "https://api.ithbat.io/api/v1/permissions/c3d4e5f6-a7b8-9012-cdef-012345678902" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>"

Response 200

{
  "success": true,
  "data": null
}

---

Permission Object

Field	Type	Description
id	string	UUID of the permission
tenantId	string	UUID of the owning tenant
name	string	Unique identifier in resource:action format
displayName	string	Human-readable label
description	string	Optional longer description
category	string	Grouping label for display purposes
isSystem	boolean	true for built-in Ithbat IAM permissions; these are read-only
createdAt	string	ISO 8601 creation timestamp