Skip to content

roles.md

Latest commit

 

History

History
92 lines (66 loc) · 3.3 KB

roles.md

File metadata and controls

92 lines (66 loc) · 3.3 KB
Raw

Roles

Roles group users into authorization tiers. Each role can be granted different permissions per resource and action, giving you fine-grained control over who can read, create, update, or delete data.

Roles management in the Admin Console

Defining a Role

Create a role through the admin API:

{
  "name": "editor",
  "description": "Can read and update all published content",
  "enabled": true
}

Role properties:

Property Type Required Description
name string yes Unique identifier (alphanumeric and underscores)
description string no Human-readable description (max 500 characters)
enabled boolean no Whether the role is active (defaults to true)

Role names must start with a letter or underscore, contain only alphanumeric characters and underscores, and be at most 100 characters long.

Assigning Roles to Users

Each user has a primaryRole that determines their permissions at request time. Users may also have an allowedRoles array listing additional roles they can adopt.

User Field Purpose
primaryRole Active role used for authorization decisions
allowedRoles Set of roles the user is permitted to switch to

New users are automatically assigned the default role configured by the SNAAPI_DEFAULT_ROLE environment variable (defaults to "user").

Admin Role

The admin role has special behavior:

Default Full Access

When no explicit permission is defined for the admin role on a given resource, admin users automatically receive full access to all fields for all actions. This means you do not need to create permission entries for admin users unless you want to restrict their access.

Explicit Overrides

If you create a permission for the admin role on a specific resource and action, that explicit definition replaces the default full-access behavior. This lets you limit admin access when needed. For example, you can hide sensitive fields even from admins.

Admin Token Restrictions

When an admin authenticates with an API key (admin token), write operations on resource endpoints are blocked:

Operation Resource Endpoint Allowed
GET (read) yes yes
DELETE yes yes
POST (create) resource endpoint no
PUT/PATCH (update) resource endpoint no

Create and update requests via admin tokens return a 403 response with code ADMIN_TOKEN_NOT_ALLOWED. Use the dedicated admin endpoints for write operations instead.

Default Role Configuration

Set the role automatically assigned to new users:

SNAAPI_DEFAULT_ROLE=user

If this variable is not set, Snaapi defaults to "user". Make sure the role name you specify here has been created. Otherwise new users will have a role with no matching permissions.