Roles

Endpointhttps://api.kontorion.eu/v1

List the org's roles

GET

https://api.kontorion.eu/v1

/roles

Returns every role in the active organization, including the seeded admin and member built-ins (flagged with is_builtin=true). Each entry includes the resolved permission list and the count of users assigned to the role.

List the org's roles › Headers

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

List the org's roles › Responses

array | null · required

Create a custom role

POST

https://api.kontorion.eu/v1

/roles

Creates a custom role with the supplied permissions. Built-in names ("admin", "member") are reserved. Each permission must be in the catalog (see GET /v1/permissions) and assignable (not system-only).

Create a custom role › Headers

Idempotency-Key

string · required

Unique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a custom role › Request Body

description

string

name

string

permissions

array | null

Create a custom role › Responses

Created

object · required

Fetch one role

GET

https://api.kontorion.eu/v1

/roles/{id}

Returns one role's permission list and assignment count. 404 when the role belongs to a different organization (cross-tenant guard).

Fetch one role › path Parameters

id

string · required

Keycloak group UUID

Fetch one role › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Fetch one role › Responses

object · required

Delete a custom role

DELETE

https://api.kontorion.eu/v1

/roles/{id}

Removes the role. Refuses if the role still has members assigned (409 ROLE_HAS_MEMBERS - reassign first) or if it's a built-in (409 ROLE_BUILTIN_IMMUTABLE).

Delete a custom role › path Parameters

id

string · required

Keycloak group UUID

Delete a custom role › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a custom role › Responses

No Content

No data returned

Update a custom role

PATCH

https://api.kontorion.eu/v1

/roles/{id}

Replaces the role's permission list with the supplied one. The change reflects in each member's next refresh-token call. Built-ins cannot be modified (409 ROLE_BUILTIN_IMMUTABLE).

Update a custom role › path Parameters

id

string · required

Keycloak group UUID

Update a custom role › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a custom role › Request Body

description

string

name

string

permissions

array | null

Update a custom role › Responses

object · required

Portal Config Schedule

List the org's roles

GET

https://api.kontorion.eu/v1

/roles

List the org's roles › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List the org's roles › Responses

array | null · required

Create a custom role

POST

https://api.kontorion.eu/v1

/roles

Create a custom role › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a custom role › Request Body

description

string

name

string

permissions

array | null

Create a custom role › Responses

Created

object · required

Fetch one role

GET

https://api.kontorion.eu/v1

/roles/{id}

Returns one role's permission list and assignment count. 404 when the role belongs to a different organization (cross-tenant guard).

Fetch one role › path Parameters

id

string · required

Keycloak group UUID

Fetch one role › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Fetch one role › Responses

object · required

Delete a custom role

DELETE

https://api.kontorion.eu/v1

/roles/{id}

Removes the role. Refuses if the role still has members assigned (409 ROLE_HAS_MEMBERS - reassign first) or if it's a built-in (409 ROLE_BUILTIN_IMMUTABLE).

Delete a custom role › path Parameters

id

string · required

Keycloak group UUID

Delete a custom role › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a custom role › Responses

No Content

No data returned

Update a custom role

PATCH

https://api.kontorion.eu/v1

/roles/{id}

Replaces the role's permission list with the supplied one. The change reflects in each member's next refresh-token call. Built-ins cannot be modified (409 ROLE_BUILTIN_IMMUTABLE).

Update a custom role › path Parameters

id

string · required

Keycloak group UUID

Update a custom role › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a custom role › Request Body

description

string

name

string

permissions

array | null

Update a custom role › Responses

object · required