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.
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, hiding 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.