Identity & access

Custom roles and permission bindings

Lets a project give a user less than their built-in role allows, using named roles over a fixed permission catalogue.

Available in previewEngine edition 5f8ea3af

What it does

A project can define named roles from a catalogue of 41 permissions, bind them to users with an optional expiry, and have a request-level overlay narrow what those users can do. Built-in roles stay the ceiling, and custom bindings restrict and never widen.

How it works

The catalogue names permissions in groups: data (read, create, update, delete, mutate), schema, search, files, realtime, functions, users, agents, integrations, infrastructure, backups, audit, privacy, pipelines and RBAC itself. A role is a name plus 1 to 64 permission entries, and a trailing .* grants a whole group, for example data.*. Four system roles (viewer, editor, admin, super_admin) are fixed and cannot be edited.

A binding attaches a role to a user in a project and can carry an expiry time. A user with no active binding is unaffected: the overlay does nothing and the built-in role decides. A user with one or more active bindings is restricted. A request is allowed when the union of their roles grants the permission the route maps to and their built-in role also allows it, so a custom role can never grant more than the built-in role.

The overlay is middleware that runs on requests. It maps the method and path to a permission, for example GET under /rest/v1 to data.read, POST under /v1/files to files.write and /admin/audit to audit.read, then evaluates the caller's bindings. Roles, bindings and an evaluation endpoint are managed under /admin/v1/projects/:id/rbac with a project service key or a platform session, and every change is written to the audit log.

The effective-permissions endpoint shows what a user's active bindings add up to, and the evaluation endpoint answers whether a named permission would be allowed, so a role can be tested before it is bound. Deleting a role that is still assigned is refused, and a binding is checked against the project's users before it is accepted.

Where you reach it

  • HTTPGET /admin/v1/projects/:id/rbac/catalog
  • HTTPGET|POST /admin/v1/projects/:id/rbac/roles, PUT|DELETE /admin/v1/projects/:id/rbac/roles/:role
  • HTTPGET|POST /admin/v1/projects/:id/rbac/bindings, DELETE /admin/v1/projects/:id/rbac/bindings/:binding
  • HTTPGET /admin/v1/projects/:id/rbac/subjects/:user/effective, POST /admin/v1/projects/:id/rbac/evaluations

Example

Create a role and bind it to a userbash
# Create a role with two permissions (the project's service key manages its own project)
curl -s -X POST "$KYNETRA_URL/admin/v1/projects/$PROJECT_ID/rbac/roles" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"support-readonly","description":"Read data and search","permissions":["data.read","search.execute"]}'
# returns {"role": {"id": "...", ...}}

# Bind it to a user: from now on that user is limited to these permissions
curl -s -X POST "$KYNETRA_URL/admin/v1/projects/$PROJECT_ID/rbac/bindings" \
  -H "Authorization: Bearer $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"<user id>","role_id":"<role id>"}'

Limits

  • The overlay narrows access and cannot widen it. Built-in roles and collection rules stay the ceiling.
  • It applies to requests that carry a user identity inside a project: project end-user tokens and platform sessions acting in a project. Service keys and the global key carry no user identity and are not narrowed.
  • The permission catalogue is fixed. Custom permissions cannot be defined, and routes that map to no catalogue entry are not narrowed.
  • A role holds at most 64 permission entries.

Evidence

  • On this siteSecurity overview
  • Tests10 RBAC tests (catalogue and route mapping, restriction and union of roles, no binding preserves access, expired binding ignored, wildcard grants isolated per project, validation, rebuild from the log, project-bound credentials cannot cross project paths) and 2 tests that refuse forged roles and bindings through the generic write routes

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to try this against your own workload.