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:

• ["*"]: Access to all fields
• ["id", "name", "price"]: Access limited to specific fields

Conditions

The conditions property limits the scope of the permission using filtering expressions:

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

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

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)
• 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