Admin API

Admin 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: resource:read grants list/get access. resource:write grants create/update/delete access.

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

Roles

Roles are named collections of permissions assigned to users. The system ships with built-in roles that cannot be deleted.

GET /api/v1/roles

Permission: role:read

List all roles in the tenant.

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

Response 200

{
  "items": [
    {
      "id": "r1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tenantId": "3e7a9f12-4b2c-4d8e-a1f0-9c2b3d4e5f6a",
      "name": "Support Engineer",
      "description": "Read access to users and audit logs",
      "permissions": ["user:read", "audit:read"],
      "isSystem": false,
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-01-15T10:00:00Z"
    }
  ],
  "totalItems": 1
}

GET /api/v1/roles/{id}

Permission: role:read

Get a single role by ID.

GET /api/v1/roles/permissions

Permission: role:read

Get the list of all available permissions that can be assigned to roles.

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

POST /api/v1/roles

Permission: role:write

Create a new role.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Role name (unique within tenant)
`description`	string	No	Human-readable description
`permissions`	string[]	No	Initial permissions to grant

curl -X POST "https://api.ithbat.io/api/v1/roles" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Engineer",
    "description": "Read access to users and audit logs",
    "permissions": ["user:read", "audit:read"]
  }'

Response 201 — Returns the created role object.

PUT /api/v1/roles/{id}

Permission: role:write

Update a role's name, description, or permissions. System roles cannot be modified.

Request Body — All fields optional:

Field	Type	Description
`name`	string	New role name
`description`	string	New description
`permissions`	string[]	Replaces the entire permissions list

DELETE /api/v1/roles/{id}

Permission: role:write

Delete a custom role. System roles cannot be deleted. Users with only this role will lose those permissions immediately.

Permissions

GET /api/v1/permissions

Permission: permission:read

List all permissions in the tenant.

GET /api/v1/permissions/categories

Permission: permission:read

List permissions grouped by category.

GET /api/v1/permissions/{id}

Permission: permission:read

Get a permission by ID.

POST /api/v1/permissions

Permission: permission:write

Create a custom permission.

PUT /api/v1/permissions/{id}

Permission: permission:write

Update a permission.

DELETE /api/v1/permissions/{id}

Permission: permission:write

Delete a custom permission.

Groups

Groups are collections of users. Assign roles to groups to apply permissions to all members at once.

GET /api/v1/groups

Permission: group:read

List all groups in the tenant.

curl "https://api.ithbat.io/api/v1/groups?page=1&limit=25" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>"

GET /api/v1/groups/{id}

Permission: group:read

Get a group by ID.

GET /api/v1/groups/{id}/members

Permission: group:read

List members of a group.

GET /api/v1/groups/{id}/roles

Permission: group:read

List roles assigned to a group.

POST /api/v1/groups

Permission: group:write

Create a new group.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Group name (unique within tenant)
`description`	string	No	Group description

curl -X POST "https://api.ithbat.io/api/v1/groups" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Tenant-ID: <tenant_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Team",
    "description": "Backend engineers"
  }'

Response 201 — Returns the created group object.

PUT /api/v1/groups/{id}

Permission: group:write

Update a group's name or description.

DELETE /api/v1/groups/{id}

Permission: group:write

Delete a group. Members are not deleted — they lose any permissions inherited through this group.

POST /api/v1/groups/{id}/members

Permission: group:write

Add a user to the group.

Request Body

Field	Type	Required	Description
`userId`	string	Yes	UUID of the user to add

DELETE /api/v1/groups/{id}/members/{uid}

Permission: group:write

Remove a user from the group.

POST /api/v1/groups/{id}/roles

Permission: group:write

Assign a role to the group. All group members inherit the role's permissions.

Request Body

Field	Type	Required	Description
`roleId`	string	Yes	UUID of the role to assign

DELETE /api/v1/groups/{id}/roles/{rid}

Permission: group:write

Remove a role from the group.

Organizations

Organizations model external companies, departments, or sub-entities within a tenant. Users can belong to multiple organizations with different roles in each.

GET /api/v1/organizations

Permission: organization:read

List all organizations in the tenant.

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

GET /api/v1/organizations/{id}

Permission: organization:read

Get an organization by ID.