Kaiten

Core Concepts

Users & Roles

What each person may do in an organization — the roles and scopes Kaiten stores for every membership and reads on every request, whatever the identity provider's token carries.

The identity provider says who a person is and which organization they act in. What that person may do is decided in Kaiten: every membership holds roles and scopes, stored per organization and read again on every request — REST, GraphQL and OFREP alike. The scopes, roles or permissions a token carries are not read, whatever their value.

Scopes and roles

A scope is an action on a resource — read:customers, write:licenses — from the vocabulary of the scopes page; write: includes read:. A role is a named group of scopes. Three roles are built in, and cannot be edited or deleted:

RoleScopesWhat it grants
Administrator (administrator)write:*Everything in the organization, managing users and roles included
Viewer (viewer)Every read: scopeReading every resource
Editor (editor)Every write: scopeReading and writing every resource — write:users included, so an editor manages people, but never the Administrator role

An organization adds its own roles: a name, a description, an identifier that cannot change (lowercase letters, digits and hyphens, starting with a letter, up to 64 characters), and scopes from the same vocabulary. Wildcards are refused, so write:* belongs to the built-in Administrator alone. A role's scopes are expanded on every request: editing a role changes the access of everyone who holds it, from their next request, with the token they already have.

A person holds roles, scopes of their own — direct scopes — or both, and their access is the union. Every enabled member also holds read:profile, which reads their own profile, roles and effective scopes.

The first administrator

Each organization elects its first administrator once: the first eligible person to sign in to it. Arrival order decides — an invited member who signs in before the person who created the organization is the one elected — and Kaiten reads no role, owner or setting from the identity provider to choose. Eligible means a person whose sign-in is accepted, never a service account or the platform identity, in an organization where no one's access is stored yet: an organization that already holds someone's access, even access that grants nothing or a disabled person's, keeps it and elects no one. Organizations elect independently, a second one on the same installation included, and simultaneous first sign-ins elect a single person.

The election is not run again — not after the person it elected is demoted, disabled or deleted, not after everyone's access is removed, and not after the organization is deleted and a later sign-in recreates it. Upgrading an installation that already has people to the release that introduced users and roles makes every existing member an administrator, once, at the upgrade. Upgrading to 26.10.9, the release that elects per organization, keeps every organization that holds stored access or a custom role as it is; one that holds neither elects at its next sign-in, possibly a member who joined before the upgrade.

Everyone else who signs in for the first time joins their organization with no access beyond their own profile, until someone assigns them roles or scopes.

Keep more than one administrator. The last enabled administrator can neither be disabled nor lose the role, and any administrator can appoint others, the original one included. The console warns when only one remains and offers Grant administrator access in another person's access editor.

In the console

Settings › Users & roles has two tabs. Users lists the organization's people, with their roles, their direct scopes and their status, filtered by a search and a status.

The Users tab of Settings › Users & roles with five people: Splinter, marked You, and April O'Neil, both Administrator; Leonardo, Release Manager; Raphael, Customer Success with 1 direct scope; and Donatello, Customer Success, disabled. Each row has a Manage button.The Users tab of Settings › Users & roles with five people: Splinter, marked You, and April O'Neil, both Administrator; Leonardo, Release Manager; Raphael, Customer Success with 1 direct scope; and Donatello, Customer Success, disabled. Each row has a Manage button.

Manage opens a person's access editor: the roles to assign, the direct scopes under Advanced: direct scope overrides, and the Effective resource access that results — for each resource, its level and whether it comes from a role or a direct grant. Save access applies the change from the person's next request. Disable user ends their access to this organization from their next request and keeps their roles and direct scopes for a later re-enable. A person's name and email are shared by every organization they belong to, and once edited here the identity provider's claims no longer overwrite them; their roles and access apply to this organization only.

Raphael's access editor over the users list: the roles Viewer and Editor, 21 scopes each, Customer Success, checked, 3 scopes, and Release Manager; the collapsed Advanced: direct scope overrides; and the effective resource access — Customers read and write, Instances and Licenses read, all from roles, and Feature flags read, from a direct grant — above Save access.Raphael's access editor over the users list: the roles Viewer and Editor, 21 scopes each, Customer Success, checked, 3 scopes, and Release Manager; the collapsed Advanced: direct scope overrides; and the effective resource access — Customers read and write, Instances and Licenses read, all from roles, and Feature flags read, from a direct grant — above Save access.

Roles lists the built-in and custom roles, with the access each grants and how many people hold it. Create role asks for a name, the role identifier, a description, and a level per resource — None, Read, or Read & write. A role that someone still holds cannot be deleted; built-in roles open read-only.

The Roles tab: the three built-in roles, Administrator, with full organization access and user and role administration, held by 2 people, Viewer and Editor, 21 scopes each, held by no one; then the custom roles Customer Success, 3 scopes, held by 2, and Release Manager, 3 scopes, held by 1. The Create role button sits beside the search.The Roles tab: the three built-in roles, Administrator, with full organization access and user and role administration, held by 2 people, Viewer and Editor, 21 scopes each, held by no one; then the custom roles Customer Success, 3 scopes, held by 2, and Release Manager, 3 scopes, held by 1. The Create role button sits beside the search. The Role details dialog of Customer Success: its name, its identifier customer-success, which cannot change, its description, and a level per resource — None, Read, or Read & write — with Customers at Read & write, and Add-ons, Billing, Components, Customer sessions and Deployment zones at None. The footer says the changes affect 2 assigned users, beside Cancel and Save.The Role details dialog of Customer Success: its name, its identifier customer-success, which cannot change, its description, and a level per resource — None, Read, or Read & write — with Customers at Read & write, and Add-ons, Billing, Components, Customer sessions and Deployment zones at None. The footer says the changes affect 2 assigned users, beside Cancel and Save.

What a manager can grant

read:users opens the directory of people and roles; write:users manages them. Both come from roles or direct scopes, like any other scope, and three rules bound every change:

  • Only what you hold. Managing a person requires holding both their current access and the access you give them, so nobody edits, demotes or disables someone with more access than their own. Granting or managing the Administrator role requires write:* itself — holding every scope one by one is not enough. The API answers 403 Users.CannotDelegate, or 403 Users.MissingPermission to a caller without write:users.
  • Never the last administrator. Disabling or demoting the last enabled administrator answers 409 Users.LastAdministrator.
  • People only. These operations act for a person: a service account's token is refused, even when it carries read:users or write:users.

Editing or deleting a built-in role answers 409 Users.BuiltInRole, deleting a role someone holds 409 Users.RoleInUse, and creating a role under an identifier already taken 409 Users.RoleAlreadyExists.

Over the API

MethodPathScopeDoes
GET/meread:profileYour profile, roles and effective scopes, with the organization's roles and scope vocabulary
GET/usersread:usersThe organization's people, paginated
GET/users/{id}read:usersOne person
PUT/users/{id}write:usersReplace their name and email
PATCH/users/{id}/assignmentswrite:usersReplace their roles and direct scopes, keeping their status
PATCH/users/{id}/enabledwrite:usersEnable or disable them, keeping their roles and scopes
PUT/users/{id}/authorizationwrite:usersReplace roles, direct scopes and status at once
GET/rolesread:usersThe built-in and custom roles
POST/roleswrite:usersCreate a custom role
PUT/roles/{slug}write:usersReplace a custom role's name, description and scopes
DELETE/roles/{slug}write:usersDelete a custom role nobody holds

Where to go next

Scopes

The vocabulary roles are made of: every module, what read and write open, and the presets for service account tokens.

Identity Provider

Who signs people in, the claims Kaiten reads, and how an organization and its first members appear.

Authentication

The credentials Kaiten accepts — people, service accounts, the platform identity — and what each one may call.

Metadata Fields

Typed, JSON-Schema-validated properties you declare on instances and deployment zones — rendered in the console, enforced on every write, readable by targeting rules.

The Audit Trail

Every change and every evaluation, recorded in one trail — the memory of the system, and the answer to "who had access to what, when?"

On this page

Scopes and roles
The first administrator
In the console
What a manager can grant
Over the API
Where to go next