Master PB API Rules

A comprehensive skill for PocketBase API rules and filter expressions — covering collection security rules, filter syntax, relation traversal, admin vs. client access patterns, and real-time subscription security for PocketBase applications.

When to Use This Skill

Choose Master PB API Rules when you need to:

• Configure collection API rules for read, write, and delete access
• Write filter expressions for complex data queries
• Secure collections with user-based access controls
• Set up proper admin vs. client access patterns
• Configure real-time subscription security

Consider alternatives when:

• You need PocketBase collection schema design (use a PB collections skill)
• You need PocketBase deployment configuration (use a PB deploy skill)
• You need general REST API design (use an API design skill)

Quick Start

Copy
# Set API rules via PocketBase Admin UI or migration
# Navigate to: Admin → Collections → [Collection] → API Rules

Copy
// PocketBase API rules are set as filter expressions

// Example: Users collection rules
{
  "listRule": "",                    // Anyone can list (empty = allow all authenticated)
  "viewRule": "",                    // Anyone can view
  "createRule": "",                  // Anyone authenticated can create
  "updateRule": "id = @request.auth.id",  // Users can only update themselves
  "deleteRule": "id = @request.auth.id",  // Users can only delete themselves
}

// Example: Posts collection with author-based access
{
  "listRule": "published = true || author = @request.auth.id",
  "viewRule": "published = true || author = @request.auth.id",
  "createRule": "@request.auth.id != ''",
  "updateRule": "author = @request.auth.id",
  "deleteRule": "author = @request.auth.id",
}

Core Concepts

Rule Types

Rule	Controls	Locked Value	Empty String	null
listRule	List/search records	Admin only	All auth users	Public
viewRule	View single record	Admin only	All auth users	Public
createRule	Create new records	Admin only	All auth users	Public
updateRule	Update existing records	Admin only	All auth users	Public
deleteRule	Delete existing records	Admin only	All auth users	Public

Filter Expression Syntax

Copy
// Comparison operators
"field = value"           // Equal
"field != value"          // Not equal
"field > value"           // Greater than
"field >= value"          // Greater or equal
"field < value"           // Less than
"field <= value"          // Less or equal
"field ~ 'pattern'"       // LIKE (case-insensitive)
"field !~ 'pattern'"      // NOT LIKE

// Logical operators
"condition1 && condition2" // AND
"condition1 || condition2" // OR

// Special variables
"@request.auth.id"        // Current authenticated user ID
"@request.auth.email"     // Current user email
"@request.data.field"     // Submitted form data field
"@collection.name.field"  // Cross-collection reference

// Relation traversal
"author.role = 'admin'"   // Traverse relation to check field
"comments_via_post.user = @request.auth.id"  // Back-relation

// Array/multi-relation checks
"tags ?= 'javascript'"    // Any tag matches
"tags ?!= 'spam'"         // No tag matches 'spam'

Common Access Patterns

Copy
// Owner-only access
"user = @request.auth.id"

// Owner or admin
"user = @request.auth.id || @request.auth.role = 'admin'"

// Published content (public) + drafts (owner only)
"status = 'published' || author = @request.auth.id"

// Team-based access (via relation)
"team.members ?= @request.auth.id"

// Prevent field modification
// updateRule that checks submitted data:
"author = @request.auth.id && @request.data.author:isset = false"

// Time-based rules
"created > @now - 86400"  // Only records from last 24 hours

// Nested relation check
"organization.owner = @request.auth.id"

Configuration

Parameter	Description	Example
collection	Target collection name	"posts"
rule_type	Which rule to configure	"listRule" / "updateRule"
auth_required	Whether authentication is required	true
owner_field	Field linking record to user	"author" / "user"
public_read	Allow unauthenticated reads	true (set rule to null)
admin_only	Restrict to admin access	false (lock rule)

Best Practices

1. Start with locked rules and open selectively — New collections should have all rules locked (admin only). Open access incrementally as you define who should access what. It's much safer to add permissions than to realize you forgot to restrict them.

2. Use @request.data.field:isset to prevent unauthorized field changes — Combine with update rules to prevent users from changing fields they shouldn't. For example, prevent a user from reassigning a post to another author: author = @request.auth.id && @request.data.author:isset = false.

3. Test rules with different user contexts — Log in as different users (owner, non-owner, unauthenticated) and verify each rule works correctly. The PocketBase API preview in the admin UI lets you test queries with different auth contexts.

4. Use relation traversal for team-based access — Instead of duplicating user IDs, create a teams collection with a members relation, then check team.members ?= @request.auth.id in your rules. This scales better and centralizes permission management.

5. Document your API rules alongside your schema — API rules are as important as your schema design but often undocumented. Create a security matrix that maps each collection to its rules with justification for each access level.

Common Issues

Empty string vs. null confusion — An empty string rule ("") requires authentication but allows all authenticated users. A null rule allows everyone including unauthenticated users. Mixing these up creates either overly restrictive or dangerously open access. Test with unauthenticated requests to verify.

Filter expressions silently fail with wrong field names — If you reference a field that doesn't exist, PocketBase may return empty results instead of an error. Double-check field names match your schema exactly, including case sensitivity.

Back-relations don't work without proper naming — To use back-relations like comments_via_post, the relation field in the child collection must be named exactly as referenced. The pattern is {collection}_via_{field}. If the comments collection has a field called post_id instead of post, the back-relation name changes accordingly.