Permission Routes

← Back to Documentation Home

Table of Contents

1. Get Role Permissions
2. Create Permission
3. Update Permission
4. Delete Permission
5. Bulk Update Permissions

Get Role Permissions

Retrieve all permissions for a specific role.

• URL: /permissions/:roleId
• Method: GET
• Auth required: Yes (Admin role)

URL Parameters

Query Parameters

Success Response

• Code: 200 OK
• Content:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "role_Id": "4a7d1ed4-8d7f-44b3-8f5e-7e5f2d8a7d3c",
      "collection": "products",
      "action": "read",
      "fields": ["*"],
      "conditions": {},
      "createdAt": "2023-06-01T12:00:00Z",
      "updatedAt": "2023-06-01T12:00:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "role_Id": "4a7d1ed4-8d7f-44b3-8f5e-7e5f2d8a7d3c",
      "collection": "products",
      "action": "create",
      "fields": ["name", "description", "price", "category_id"],
      "conditions": {},
      "createdAt": "2023-06-01T12:00:00Z",
      "updatedAt": "2023-06-01T12:00:00Z"
    }
  ]
}

Error Responses

• Code: 401 Unauthorized

  • Content: { "error": { "message": "Authentication required" } }

• Code: 403 Forbidden

  • Content: { "error": { "message": "Insufficient permissions" } }

• Code: 404 Not Found

  • Content: { "error": { "message": "Role not found" } }

• Code: 500 Internal Server Error

  • Content: { "error": { "message": "Error retrieving permissions" } }

Create Permission

Create a new permission for a role.

• URL: /permissions
• Method: POST
• Auth required: Yes (Admin role)
• Content-Type: application/json

Request Body

Example:

{
  "role_Id": "4a7d1ed4-8d7f-44b3-8f5e-7e5f2d8a7d3c",
  "collection": "products",
  "action": "read",
  "fields": ["*"],
  "conditions": {
    "user_id": { "$CURRENT_USER": "id" }
  },
  "tenant_Id": "8a7d1ed4-8d7f-44b3-8f5e-7e5f2d8a7d3c"
}

Success Response

• Code: 201 Created
• Content:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "role_Id": "4a7d1ed4-8d7f-44b3-8f5e-7e5f2d8a7d3c",
    "collection": "products",
    "action": "read",
    "fields": ["*"],
    "conditions": {
      "user_id": { "$CURRENT_USER": "id" }
    },
    "tenant_Id": "8a7d1ed4-8d7f-44b3-8f5e-7e5f2d8a7d3c",
    "createdAt": "2023-06-01T12:00:00Z",
    "updatedAt": "2023-06-01T12:00:00Z"
  }
}

Error Responses

• Code: 400 Bad Request

  • Content: { "error": { "message": "Invalid permission data" } }

• Code: 401 Unauthorized

  • Content: { "error": { "message": "Authentication required" } }

• Code: 403 Forbidden

  • Content: { "error": { "message": "Insufficient permissions" } }

• Code: 500 Internal Server Error

  • Content: { "error": { "message": "Error creating permission" } }

Update Permission

Update an existing permission.

• URL: /permissions/:id
• Method: PATCH
• Auth required: Yes (Admin role)
• Content-Type: application/json

URL Parameters

Request Body

Example:

{
  "fields": ["id", "name", "price", "description"],
  "conditions": {
    "status": "active"
  }
}

Success Response

• Code: 200 OK
• Content:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "role_Id": "4a7d1ed4-8d7f-44b3-8f5e-7e5f2d8a7d3c",
    "collection": "products",
    "action": "read",
    "fields": ["id", "name", "price", "description"],
    "conditions": {
      "status": "active"
    },
    "tenant_Id": "8a7d1ed4-8d7f-44b3-8f5e-7e5f2d8a7d3c",
    "createdAt": "2023-06-01T12:00:00Z",
    "updatedAt": "2023-06-01T13:30:00Z"
  }
}

Error Responses

• Code: 400 Bad Request

  • Content: { "error": { "message": "Invalid permission data" } }

• Code: 401 Unauthorized

  • Content: { "error": { "message": "Authentication required" } }

• Code: 403 Forbidden

  • Content: { "error": { "message": "Insufficient permissions" } }

• Code: 404 Not Found

  • Content: { "error": { "message": "Permission not found" } }

• Code: 500 Internal Server Error

  • Content: { "error": { "message": "Error updating permission" } }

Delete Permission

Delete a permission.

• URL: /permissions/:id
• Method: DELETE
• Auth required: Yes (Admin role)

URL Parameters

Success Response

• Code: 200 OK
• Content:

{
  "message": "Permission deleted successfully"
}

Error Responses

• Code: 401 Unauthorized

  • Content: { "error": { "message": "Authentication required" } }

• Code: 403 Forbidden

  • Content: { "error": { "message": "Insufficient permissions" } }

• Code: 404 Not Found

  • Content: { "error": { "message": "Permission not found" } }

• Code: 500 Internal Server Error

  • Content: { "error": { "message": "Error deleting permission" } }

Bulk Update Permissions

Update multiple permissions for a role in a single operation.

• URL: /permissions/bulk/:roleId
• Method: POST
• Auth required: Yes (Admin role)
• Content-Type: application/json

URL Parameters

Query Parameters

Request Body

Example:

{
  "permissions": [
    {
      "collection": "products",
      "action": "read",
      "fields": ["*"],
      "conditions": {}
    },
    {
      "collection": "products",
      "action": "create",
      "fields": ["name", "description", "price", "category_id"],
      "conditions": {}
    },
    {
      "collection": "products",
      "action": "update",
      "fields": ["name", "description", "price"],
      "conditions": {
        "user_id": { "$CURRENT_USER": "id" }
      }
    },
    {
      "collection": "products",
      "action": "delete",
      "fields": [],
      "conditions": {
        "user_id": { "$CURRENT_USER": "id" }
      }
    }
  ]
}

Success Response

• Code: 200 OK
• Content:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "role_Id": "4a7d1ed4-8d7f-44b3-8f5e-7e5f2d8a7d3c",
      "collection": "products",
      "action": "read",
      "fields": ["*"],
      "conditions": {},
      "tenant_Id": "8a7d1ed4-8d7f-44b3-8f5e-7e5f2d8a7d3c",
      "createdAt": "2023-06-01T12:00:00Z",
      "updatedAt": "2023-06-01T12:00:00Z"
    }
    // ... other permissions
  ],
  "message": "Permissions updated successfully"
}

Error Responses

• Code: 400 Bad Request

  • Content: { "error": { "message": "Invalid permissions data" } }

• Code: 401 Unauthorized

  • Content: { "error": { "message": "Authentication required" } }

• Code: 403 Forbidden

  • Content: { "error": { "message": "Insufficient permissions" } }

• Code: 404 Not Found

  • Content: { "error": { "message": "Role not found" } }

• Code: 500 Internal Server Error

  • Content: { "error": { "message": "Error updating permissions" } }

Permission Structure

Actions

The following actions can be assigned as permissions:

• read: Allows reading items from a collection
• create: Allows creating new items in a collection
• update: Allows updating existing items in a collection
• delete: Allows deleting items from a collection

Fields

The fields property controls which fields the role can access. BAASIX supports powerful wildcard patterns for field-level permissions.

Wildcard Patterns

Pattern Matching Rules

• Each * segment matches exactly one level. * = own fields; author.* = the author relation's direct fields (allows author.name but not author.role.name).
• To go deeper, add another .* per level: author.*.* allows author.role.name (the author's relations, one level further). There is no **syntax — use repeated.\* segments.
• Critical: a bare * grants only the collection's own columns. Any relation you want returned must be named explicitly (e.g. "author.*"). A relation not listed in fields is omitted from the response entirely, even if relConditions targets it.

Examples

1. All fields access:

   { "fields": ["*"] }

   Allows access to the collection's own/direct fields only. This does not include any relations — to return a relation, add it explicitly (e.g. ["*", "author.*"]).

2. Specific fields only:

   { "fields": ["id", "name", "email", "status"] }

   Allows access only to the specified fields.

3. All fields plus one relation:

   { "fields": ["*", "author.*"] }

   Allows access to all direct fields plus all fields of the author relation.

4. All fields plus nested relations (one level):

   { "fields": ["*", "author.*", "category.*"] }

   Allows access to all direct fields plus all fields of author and category relations.

5. Full relation tree access:

   { "fields": ["*", "posts.*.*"] }

   Allows access to all direct fields plus the entire posts relation tree (posts, posts.comments, posts.comments.author, etc.)

6. Mixed specific and wildcard:

   { "fields": ["id", "title", "author.name", "author.email", "category.*"] }

   Allows access to specific fields from the main collection, specific fields from author, and all fields from category.

7. Restricted sensitive data:

   { "fields": ["id", "name", "email", "author.id", "author.name"] }

   Allows access to specific fields only - useful for hiding sensitive data like passwords, internal IDs, etc.

Conditions

The conditions property limits the scope of the permission using filtering expressions. This applies to the main collection being queried — it decides which existing records of this collection the role can access (RLS "USING" semantics). It applies to read, update, and delete grants.

conditions is not valid on create grants — there are no existing rows to filter, so the API rejects it with a 400. To scope what a role may create, use checkConditions.

conditions vs relConditions: conditions filters the main records (which rows of this collection appear). relConditions filters the related rows returned inside array relations (which child rows appear in the response). They are not interchangeable — "which rows of this collection?" → conditions; "which related rows in the response?" → relConditions.

{
  "status": "active" // Only items where status is "active"
}

{
  "department_id": { "$CURRENT_USER": "department.id" } // Only items in user's department
}

{
  "created_by": { "$CURRENT_USER": "id" } // Only items created by the current user
}

Check Conditions (checkConditions)

The checkConditions property is the WITH CHECK side of row-level security (mirroring PostgreSQL RLS): it validates what a written row may become. After a create or update — once hooks, defaults, and relations have been applied, but before commit — the row is re-read with checkConditions applied as a filter. If it doesn't match, the request fails with 403 and the whole write rolls back (bulk create/update batches are atomic: one violating item rolls back the entire batch).

checkConditions: null (the default) means no post-write check — existing grants are unaffected.

{
  "collection": "tasks",
  "action": "create",
  "fields": ["*"],
  "checkConditions": { "owner_Id": { "eq": "$CURRENT_USER" } }
}

Users with this grant can only create tasks assigned to themselves — creating a task for someone else fails and rolls back.

On update, conditions and checkConditions compose — conditions decides which rows may be edited, checkConditions decides what they may become:

{
  "collection": "documents",
  "action": "update",
  "fields": ["*"],
  "conditions": { "owner_Id": { "eq": "$CURRENT_USER" }, "status": { "eq": "draft" } },
  "checkConditions": { "owner_Id": { "eq": "$CURRENT_USER" }, "status": { "in": ["draft", "submitted"] } }
}

This reads as: "you may edit your own drafts; the result must still belong to you and be draft or submitted." Submitting a draft works; archiving it or reassigning it to another user fails. Note that naively re-checking conditions after the update would forbid the legitimate draft → submitted transition — that is exactly why the two properties are separate.

checkConditions supports everything conditions does: all filter operators, dynamic variables ($CURRENT_USER, $CURRENT_USERROLE.*, …), and $path$ relation keys for cross-record rules:

{
  "collection": "leave_balance",
  "action": "create",
  "fields": ["*"],
  "checkConditions": { "$staff_profile.orguser_Id$": { "eq": "$CURRENT_USER" } }
}

Users can only create a leave balance attached to their own staff profile — the check joins through the just-created row's relation.

Additional notes:

• Rejected writes fire no after-hooks and write no audit-log rows (they never commit).
• Administrators and system-context operations are exempt.
• When a permission uses ACL entries, checkConditions is still read from the permission row itself — ACL entries don't carry it.

Relational Conditions (relConditions)

The relConditions property is a deep filter for filtering within relations that return arrays. When a permission includes O2M (One-to-Many) or M2M (Many-to-Many) relations, those return as arrays. The relConditions filters what items appear in those arrays. It is keyed by relation name and does not restrict the main records.

Note: The property is always relConditions (plural).

Prerequisite: relConditions only takes effect on relations that are also granted in fields (e.g. "reviews.*"). If a relation isn't listed in fields, it's omitted from the response entirely and relConditions for it has no effect.

When to Use relConditions

Examples

1. Filter comments array within posts:

   {
     "collection": "posts",
     "action": "read",
     "fields": ["*", "comments.*"],
     "relConditions": {
       "comments": {
         "isApproved": { "eq": true }
       }
     }
   }

   Users can read posts, but each post's comments array only contains approved comments.

2. Filter roles array for users (M2M):

   {
     "collection": "users",
     "action": "read",
     "fields": ["*", "roles.*"],
     "relConditions": {
       "roles": {
         "status": { "eq": "active" }
       }
     }
   }

   Each user's roles array only contains active roles.

3. Dynamic variables in relConditions:

   {
     "collection": "projects",
     "action": "read",
     "fields": ["*", "tasks.*"],
     "relConditions": {
       "tasks": {
         "assignedTo": { "eq": "$CURRENT_USER" }
       }
     }
   }

   Users can see all projects, but each project's tasks array only contains tasks assigned to them.

4. Nested relConditions (array within array):

   {
     "collection": "organizations",
     "action": "read",
     "fields": ["*", "departments.*", "departments.employees.*"],
     "relConditions": {
       "departments": {
         "status": { "eq": "active" },
         "employees": {
           "status": { "eq": "active" }
         }
       }
     }
   }

   Each organization's departments array contains only active departments, and each department's employees array contains only active employees.

Combining conditions and relConditions

You can use both conditions (to filter main records) and relConditions (to filter related records) together:

{
  "collection": "posts",
  "action": "read",
  "fields": ["*", "comments.*"],
  "conditions": {
    "status": "published"
  },
  "relConditions": {
    "comments": {
      "isApproved": { "eq": true }
    }
  }
}

This permission allows reading only published posts, and for those posts, only approved comments are loaded.

Dynamic Variables

Permissions support dynamic variables that reference properties of the current user, role, tenant, or settings:

• $CURRENT_USER: The ID of the authenticated user
• $CURRENT_USER.field: Any field of the user (e.g., $CURRENT_USER.email, $CURRENT_USER.department)
• $CURRENT_ROLE: The ID of the current role
• $CURRENT_ROLE.field: Any field of the role
• $CURRENT_USERROLE: The ID of the active role-assignment (baasix_UserRole) row
• $CURRENT_USERROLE.field: Any field of the assignment row, including custom columns added to baasix_UserRole (e.g., $CURRENT_USERROLE.team_id) or relational paths (e.g., $CURRENT_USERROLE.team.name)
• $CURRENT_TENANT: The ID of the current tenant (multi-tenant)
• $CURRENT_TENANT.field: Any field of the tenant (e.g., $CURRENT_TENANT.name)
• $CURRENT_SETTINGS.field: Any settings field, tenant-aware (e.g., $CURRENT_SETTINGS.currency, $CURRENT_SETTINGS.language)
• $NOW: Current timestamp
• $NOW+DAYS_7, $NOW-HOURS_2, etc.: Relative date calculations

Scoping Access by Role Assignment

$CURRENT_USERROLE is useful when a user can belong to multiple teams (or other groupings) through separate role assignments, and permissions should scope to whichever assignment is currently active.

Say baasix_UserRole has a custom team_id column (added via a relationship to a teams collection). A user who belongs to two teams has two baasix_UserRole rows, one per team. A permission condition can restrict reads to the active team:

{
  "role_Id": "member-role-uuid",
  "collection": "tasks",
  "action": "read",
  "fields": ["*"],
  "conditions": {
    "team_id": { "eq": "$CURRENT_USERROLE.team_id" }
  }
}

defaultValues can stamp the same column on create, so new records are automatically scoped to the active team:

{
  "defaultValues": {
    "team_id": "$CURRENT_USERROLE.team_id"
  }
}

The user switches their active assignment with POST /auth/switch-tenant, passing userRole_Id instead of tenant_Id:

POST /auth/switch-tenant
Authorization: Bearer <token>
Content-Type: application/json

{
  "userRole_Id": "the-other-assignment-row-id"
}

Once the new assignment is pinned, $CURRENT_USERROLE.team_id resolves to the other team's ID — so both the read condition and the create defaultValues flip to the newly active team without any other change. See Multi-Tenant Guide for details on userRole_Id switching.

Related Documentation

Data Access

• Item Routes - Permission-controlled data access
• Schema Routes - Schema-level permissions
• Schema Reference Guide - Field types and data models

Query System

• Complete Filter Reference - Dynamic variables in permission conditions ($CURRENT_USER, $CURRENT_USERROLE, $CURRENT_TENANT, $CURRENT_SETTINGS)
• Advanced Query Guide - Permission-filtered queries

Authentication

• Authentication Routes - User authentication and roles

Multi-tenant

• Multi-tenant Guide - Tenant-specific permissions and isolation

Automation

• Hooks System - Permission-related hooks

Reference

• API Routes Reference - Complete endpoint listing
• Integration Guide - Permission-aware client implementation

← Back to Documentation Home