Uebliche

Appearance

Roles ​

Admin-only endpoints to create scoped roles, attach permissions, and assign them to users. Higher weight values represent higher priority and are used when clients need to derive the most important visible role label for a user.

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
  • service
  • extension

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",
      "weight": 100,
      "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",
  "weight": 50,
  "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",
    "weight": 50,
    "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",
  "weight": 75,
  "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",
    "weight": 75,
    "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",
      "weight": 75,
      "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 }