BaasixBaasix

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

ParameterTypeRequiredDescription
roleIdstringYesID of the role

Query Parameters

ParameterTypeRequiredDescription
tenant_IdstringNoFilter by tenant ID (multi-tenant mode only)
collectionstringNoFilter permissions by collection name

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

FieldTypeRequiredDescription
role_IdstringYesID of the role
collectionstringYesCollection name for this permission
actionstringYesPermission action (read, create, update, delete)
fieldsarray/stringNoArray of field names or "*" for all fields
conditionsobjectNoConditions that limit the scope of the permission
tenant_IdstringNoTenant ID (required in multi-tenant mode)

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

ParameterTypeRequiredDescription
idstringYesPermission ID

Request Body

FieldTypeRequiredDescription
actionstringNoPermission action (read, create, update, delete)
fieldsarray/stringNoArray of field names or "*" for all fields
conditionsobjectNoConditions that limit the scope of the permission

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

ParameterTypeRequiredDescription
idstringYesPermission ID

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

ParameterTypeRequiredDescription
roleIdstringYesID of the role

Query Parameters

ParameterTypeRequiredDescription
tenant_IdstringNoTenant ID (required in multi-tenant mode)

Request Body

FieldTypeRequiredDescription
permissionsarrayYesArray of permission objects

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

PatternDescriptionExample
*Access to all direct fields["*"]
relation.*Access to all fields of a specific relation (one level deep)["*", "author.*"]
relation.*.*Access to all fields of a relation AND all its nested relations (recursive)["*", "posts.*.*"]

Pattern Matching Rules

  • * matches exactly one level - e.g., author.* allows author.name but NOT author.role.name
  • ** matches any number of levels - e.g., author.*.* allows author.name, author.role.name, author.role.permissions.id, etc.
  • ** must always be at the end of the pattern

Examples

  1. All fields access:

    { "fields": ["*"] }

    Allows access to all direct fields of the collection.

  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.

{
  "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
}

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.

Note: The property is always relConditions (plural).

When to Use relConditions

Relation TypeReturnsUse relConditions?
BelongsTo (N:1)Single objectNo
HasOne (1:1)Single objectNo
HasMany (O2M)Array✅ Yes
BelongsToMany (M2M)Array✅ Yes

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:

  • $CURRENT_USER.id: The ID of the authenticated user
  • $CURRENT_USER.role.id: The role ID of the authenticated user
  • $CURRENT_USER.email: The email of the authenticated user
  • $CURRENT_USER.[path.to.property]: Any nested property of the user object

Data Access

Query System

Authentication

Multi-tenant

Automation

Reference

← Back to Documentation Home

Files API

Verified file management from test suite

Hooks System

Verified hooks system from test suite

On this page

Permission RoutesTable of ContentsGet Role PermissionsURL ParametersQuery ParametersSuccess ResponseError ResponsesCreate PermissionRequest BodySuccess ResponseError ResponsesUpdate PermissionURL ParametersRequest BodySuccess ResponseError ResponsesDelete PermissionURL ParametersSuccess ResponseError ResponsesBulk Update PermissionsURL ParametersQuery ParametersRequest BodySuccess ResponseError ResponsesPermission StructureActionsFieldsWildcard PatternsPattern Matching RulesExamplesConditionsRelational Conditions (relConditions)When to Use relConditionsExamplesCombining conditions and relConditionsDynamic VariablesRelated DocumentationData AccessQuery SystemAuthenticationMulti-tenantAutomationReference