Permissions & Authorization

SnackBase uses a powerful expression language for defining granular access control rules.

Overview

Permissions are defined per Role and Collection. Each permission rule consists of:

Operation: create, read, update, delete
Rule Expression: A logic string that evaluates to true (allow) or false (deny)
Allowed Fields: A list of fields (or *) that are accessible

Permission Resolution Order

SnackBase resolves permissions in the following order:

Role-Specific Rules: Rules for the user’s role on the specific collection
Wildcard Collection Rules: Rules for the * collection apply if no specific collection rule matches
Deny by Default: If no rule matches, access is denied

If multiple permissions match (e.g., role + wildcard), they are combined with OR logic.

Superadmin Bypass

Users with account_id == "00000000-0000-0000-0000-000000000000" (superadmins) bypass ALL permission checks.

Rule Syntax

Variables

Variable	Description	Fields
`user`	The currently authenticated user	`id`, `email`, `role`, `account_id`, `groups`
`record`	The record being accessed	All record fields (e.g., `id`, `owner_id`, `status`)
`account`	The current account context	`id`

Operators

Category	Operator	Description	Example
Comparison	`==`	Equal to	`user.id == record.owner_id`
	`!=`	Not equal to	`record.status != "archived"`
	`<` `>`	Less/Greater than	`record.score > 10`
	`<=` `>=`	Less/Greater or equal	`record.amount >= 100`
	`in`	Membership check	`"admin" in user.groups`
Logical	`and`	Logical AND	`user.isActive and record.public`
	`or`	Logical OR	`user.role == "admin" or record.public`
	`not`	Logical NOT	`not record.is_locked`

Functions

Function	Description	Example
`contains(list, item)`	Checks if list contains item	`contains(user.groups, "manager")`
`starts_with(str, prefix)`	Checks string prefix	`starts_with(record.sku, "PROD-")`
`ends_with(str, suffix)`	Checks string suffix	`ends_with(user.email, "@company.com")`

Literals

Strings: "text" or 'text'
Numbers: 123, 45.67
Booleans: true, false
Null/None: null
Lists: ['a', 'b', 'c']

Built-in Macros

Built-in macros are predefined functions that simplify common permission patterns.

@has_group(group_name)

Check if the user belongs to a specific group.

# Allow access to managers only
@has_group("managers")

# Alternative syntax
"managers" in user.groups

@has_role(role_name)

Check if the user has a specific role.

# Allow access to admins only
@has_role("admin")

# Alternative syntax
user.role == "admin"

@owns_record() / @is_creator()

Check if the user owns the record.

# Allow users to manage their own records
@owns_record()

# Alternative syntax
user.id == record.owner_id

@in_time_range(start_hour, end_hour)

Check if the current time is within a specific hour range.

# Allow access only during business hours (9 AM - 5 PM)
@in_time_range(9, 17)

@has_permission(operation, collection)

Check if the user has a specific permission on a collection.

# Allow users who can delete posts to also manage comments
@has_permission("delete", "posts")

SQL Macros

SQL macros allow you to create custom permission logic using SQL queries.

Creating SQL Macros

POST /api/v1/macros
{
  "name": "is_department_head",
  "description": "Check if user is department head",
  "parameters": ["department_id"],
  "sql_query": "SELECT EXISTS(SELECT 1 FROM department_members WHERE user_id = :user_id AND department_id = :department_id AND role = 'head')"
}

Using SQL Macros

@is_department_header("dept_123")

SQL Macro Features

Parameter Binding: Safe parameter binding to prevent SQL injection
5-Second Timeout: Queries are automatically terminated after 5 seconds
Error Handling: Query errors return false (deny) for security
Result Caching: Results are cached per-request for performance

System Fields

System fields are automatically managed by SnackBase and cannot be written via the API.

Field	Description
`id`	Auto-generated record identifier
`account_id`	Account/tenant identifier (auto-set)
`created_at`	Record creation timestamp (auto-set)
`updated_at`	Record update timestamp (auto-set)
`created_by`	User ID who created the record (auto-set)
`updated_by`	User ID who last updated the record

Any attempt to include system fields in a request body will result in a 422 error.

Field-Level Access Control

Each permission rule can specify allowed fields:

{
  "operation": "read",
  "rule": "true",
  "fields": ["id", "title", "status"]  // Only these fields
}

Use * to allow all fields (except system fields):

{
  "operation": "read",
  "rule": "true",
  "fields": "*"  // All non-system fields
}

Field Filtering Behavior

Context	System Fields	Behavior
Request	Excluded	Only allowed fields can be written
Response	Always Included	Allowed fields + system fields are returned

Permission Caching

SnackBase uses a high-performance permission cache:

Default TTL: 5 minutes (300 seconds)
Configurable: Set via SNACKBASE_PERMISSION_CACHE_TTL_SECONDS
Automatic Invalidation: Cache is cleared when permissions change

Cache Key Format

{user_id}:{collection}:{operation}

Example: user_123:posts:read

API Endpoints

Create Permission

POST /api/v1/permissions

Request Body:

{
  "role_id": 123,
  "collection": "posts",
  "rules": {
    "create": {
      "rule": "user.role == 'admin'",
      "fields": ["title", "content"]
    },
    "read": {
      "rule": "true",
      "fields": "*"
    }
  }
}

List Permissions

GET /api/v1/permissions

Delete Permission

DELETE /api/v1/permissions/{permission_id}

Common Patterns

1. Public Read Access

Allow anyone to read records, but only admins to modify.

Operation	Rule
`read`	`true`
`create/update/delete`	`user.role == "admin"`

2. Owner-Only Access

Users can only manage their own data.

Operation	Rule
`create`	`true`
`read/update/delete`	`user.id == record.created_by`
Alternative Macro	`@is_creator()`

3. Group-Based Access

Operation	Rule
`read`	`"managers" in user.groups`
Alternative Macro	`@has_group("managers")`

4. Status-Based Workflow

Only allow updates if the record is in a specific state.

# Allow update strictly if status is 'draft' OR user is admin
(record.status == 'draft' and user.id == record.created_by) or user.role == 'admin'

5. Field-Level Restrictions

Role: employee

Operation: read
Rule: user.id == record.user_id
Allowed Fields: ["id", "name", "department"] (Exclude salary)

Role: hr_manager

Operation: read
Rule: true
Allowed Fields: * (All fields)

Best Practices

1. Deny by Default

If no rule is defined, access is denied. Only define allow rules.

2. Use Macros for Reusability

For complex logic repeated across collections, wrap it in a SQL Macro.

3. Keep Rules Simple

Complex rules impact performance. Break complex logic into SQL Macros if needed.

4. Always Use Field Filtering

Always use field limiting for sensitive data sets. Don’t rely solely on UI hiding.

5. Test Your Rules

Use the admin UI’s rule tester or create test records to verify your rules.

6. Leverage Caching

Permission results are cached for 5 minutes. Changes take effect within this window.

Core Concepts

Advanced

​Overview

​Permission Resolution Order

​Superadmin Bypass

​Rule Syntax

​Variables

​Operators

​Functions

​Literals

​Built-in Macros

​@has_group(group_name)

​@has_role(role_name)

​@owns_record() / @is_creator()

​@in_time_range(start_hour, end_hour)

​@has_permission(operation, collection)

​SQL Macros

​Creating SQL Macros

​Using SQL Macros

​SQL Macro Features

​System Fields

​Field-Level Access Control

​Field Filtering Behavior

​Permission Caching

​Cache Key Format

​API Endpoints

​Create Permission

​List Permissions

​Delete Permission

​Common Patterns

​1. Public Read Access

​2. Owner-Only Access

​3. Group-Based Access

​4. Status-Based Workflow

​5. Field-Level Restrictions

​Best Practices

​1. Deny by Default

​2. Use Macros for Reusability

​3. Keep Rules Simple

​4. Always Use Field Filtering

​5. Test Your Rules

​6. Leverage Caching

​Related Guides