uebliche

Appearance

Roles ​

Admin-only endpoints to create scoped roles, attach permissions, and assign them to users.

Auth ​

All routes require a valid API JWT and are currently restricted to the super-admin user.

Role scopes ​

Roles are scoped to one of:

  • global
  • network
  • server

When scope is not global, provide scopeId (for example a network or server id). Only one role can be marked as default per scope and scopeId combination.

List roles ​

GET /v1/admin/roles

Response:

json
{
  "items": [
    {
      "id": "671f5b8a7a8a3e6f6e6d6e6d",
      "name": "Global admin",
      "slug": "global-admin",
      "description": "Full access",
      "scope": "global",
      "scopeId": null,
      "isDefault": false,
      "permissions": ["admin:role:manage"],
      "creatorId": "c959d9f9-dcbd-4054-8c4c-d5c305997bc0",
      "createdAt": "2026-01-15T12:00:00Z",
      "updatedAt": null
    }
  ]
}

Create role ​

POST /v1/admin/roles

Body:

json
{
  "name": "Network admin",
  "slug": "network-admin",
  "description": "Manage a specific network",
  "scope": "network",
  "scopeId": "net-123",
  "isDefault": false,
  "permissions": ["connect:server:manage"]
}

Response:

json
{
  "role": {
    "id": "671f5b8a7a8a3e6f6e6d6e6f",
    "name": "Network admin",
    "slug": "network-admin",
    "description": "Manage a specific network",
    "scope": "network",
    "scopeId": "net-123",
    "isDefault": false,
    "permissions": ["connect:server:manage"],
    "creatorId": "c959d9f9-dcbd-4054-8c4c-d5c305997bc0",
    "createdAt": "2026-01-15T12:00:00Z",
    "updatedAt": null
  }
}

Update role ​

PATCH /v1/admin/roles/{roleId}

Body:

json
{
  "name": "Network admin",
  "permissions": ["connect:server:manage", "connect:member:manage"],
  "isDefault": true
}

Response:

json
{
  "role": {
    "id": "671f5b8a7a8a3e6f6e6d6e6f",
    "name": "Network admin",
    "slug": "network-admin",
    "description": "Manage a specific network",
    "scope": "network",
    "scopeId": "net-123",
    "isDefault": true,
    "permissions": ["connect:server:manage", "connect:member:manage"],
    "creatorId": "c959d9f9-dcbd-4054-8c4c-d5c305997bc0",
    "createdAt": "2026-01-15T12:00:00Z",
    "updatedAt": "2026-01-15T12:30:00Z"
  }
}

Delete role ​

DELETE /v1/admin/roles/{roleId}

Response:

json
{ "removed": 1 }

List user roles ​

GET /v1/admin/users/{userId}/roles

Response:

json
{
  "userId": "c959d9f9-dcbd-4054-8c4c-d5c305997bc0",
  "items": [
    {
      "roleId": "671f5b8a7a8a3e6f6e6d6e6f",
      "name": "Network admin",
      "slug": "network-admin",
      "scope": "network",
      "scopeId": "net-123",
      "permissions": ["connect:server:manage"],
      "expiresAt": "2026-02-01T12:00:00Z"
    }
  ]
}

Assign user role ​

POST /v1/admin/users/{userId}/roles

Body:

json
{
  "roleId": "671f5b8a7a8a3e6f6e6d6e6f",
  "expiresAt": "2026-02-01T12:00:00Z"
}

Response:

json
{
  "userId": "c959d9f9-dcbd-4054-8c4c-d5c305997bc0",
  "roleId": "671f5b8a7a8a3e6f6e6d6e6f",
  "expiresAt": "2026-02-01T12:00:00Z"
}

expiresAt is optional. When omitted, the role does not expire.

Remove user role ​

DELETE /v1/admin/users/{userId}/roles/{roleId}

Response:

json
{ "removed": 1 }