Ultrahost/ docs

Roles and policies live in Ultrahost. Every API call is checked against them. A React helper can hide a button. It cannot be the thing that allows the action.

Paths in the tables are relative to https://api.ultrahost.com/v1/projects/{projectId}. Pagination, idempotency, and errors are described in Conventions.

Create

Roles

SDKRESTDescription
authorization.createRole(name, config)POST /authorization/rolesCreate a role
authorization.getRole(name)GET /authorization/roles/{name}Retrieve a role
authorization.listRoles()GET /authorization/rolesList roles
authorization.updateRole(name, config)PATCH /authorization/roles/{name}Update a role
authorization.deleteRole(name)DELETE /authorization/roles/{name}Delete a role
authorization.assignRole(userId, role, scope?)POST /authorization/assignmentsAssign a role
authorization.revokeRole(userId, role, scope?)DELETE /authorization/assignmentsRevoke a role

Policies

SDKRESTDescription
authorization.createPolicy(name, policy)POST /authorization/policiesDefine a policy
authorization.updatePolicy(name, policy)PATCH /authorization/policies/{name}Update a policy
authorization.listPolicies()GET /authorization/policiesList policies

Creating roles and policies is admin work. The end-user client does not write them.

Configure

assignRole takes an optional scope so the same role can apply to one resource rather than the whole project.

Calls already carry the authenticated user's project and tenant. Developers do not add an owner check beside every request. When a product needs an exception, it is an explicit policy, not a one-off if in the UI.

Use

SDKRESTDescription
authorization.check(request)POST /authorization/checkCheck one permission
authorization.checkMany(requests)POST /authorization/check/batchCheck several permissions
authorization.explain(request)POST /authorization/explainExplain a decision
authorization.getUserRoles(userId)GET /authorization/users/{userId}/rolesRoles assigned to a user
ts
const allowed = await ultrahost.authorization.check({
  action: "document.delete",
  resource: "projects/project-123"
});

if (allowed) {
  // Show the delete button.
}

explain() is for debugging a decision during development and for support tools. It is not a substitute for check() on the hot path.