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 API builder, or with 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 for the API (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

The default role assigned to new users is configurable per API from the Settings tab in the API builder. If unset, Snaapi defaults to "user". Make sure the role name you choose has been created. Otherwise, new users will have a role with no matching permissions.