Security
P0 · Foundation
Authorization Layer
Define and enforce which users, roles, or services can perform actions on application resources.
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
| SDK | REST | Description |
|---|---|---|
authorization.createRole(name, config) | POST /authorization/roles | Create a role |
authorization.getRole(name) | GET /authorization/roles/{name} | Retrieve a role |
authorization.listRoles() | GET /authorization/roles | List 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/assignments | Assign a role |
authorization.revokeRole(userId, role, scope?) | DELETE /authorization/assignments | Revoke a role |
Policies
| SDK | REST | Description |
|---|---|---|
authorization.createPolicy(name, policy) | POST /authorization/policies | Define a policy |
authorization.updatePolicy(name, policy) | PATCH /authorization/policies/{name} | Update a policy |
authorization.listPolicies() | GET /authorization/policies | List 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
| SDK | REST | Description |
|---|---|---|
authorization.check(request) | POST /authorization/check | Check one permission |
authorization.checkMany(requests) | POST /authorization/check/batch | Check several permissions |
authorization.explain(request) | POST /authorization/explain | Explain a decision |
authorization.getUserRoles(userId) | GET /authorization/users/{userId}/roles | Roles assigned to a user |
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.