Access Roles Service API

Overview

The Access Roles Service API manages role-based access control (RBAC) in a multi-tenant environment. It enables businesses to:

Create and manage roles
Assign roles to users
Control access to modules and services
Manage user permissions across different tenants

API Documentation

Base URL

https://apis.prayog.io/access-roles-service/api/v1

Authentication

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID for multi-tenant support	`test-tenant`
`X-USER-ID`	Yes*	User ID for operations	`test-user`
`Authorization`	Yes*	Bearer token for RBAC service	`Bearer <token>`

*Required for specific endpoints only

Available Endpoints

Roles Management

POST /roles - Create a new role
GET /roles - List roles with pagination
GET /roles/:id - Get role details
GET /roles/:id/modules - Get role’s module access
PATCH /roles/:id - Update a role
DELETE /roles/:id - Delete a role
PUT /roles/:id/users - Assign users to role
GET /roles/:id/users - Get users in role
GET /roles/:id/users/check - Check user assignments

User Management

PUT /users/:userId/roles - Assign roles to a user
DELETE /users/:userId/roles - Revoke role from a user
GET /users/:userId/roles - Get user’s roles
GET /users/modules - Get user’s module access
GET /users/search/tenants - Search user tenant access
GET /users/tenant - Get all users for a tenant

System Endpoints

GET /data/services - Get all services with their modules
GET /data/modules - Get all modules
GET /health - Health check endpoint

API Endpoints

1. Health Check

Checks the health status of the service and its dependencies.

GET /health

Example Curl Command

curl --location 'http://localhost:9021/access-roles-service/api/v1/health'

Success Response (200 OK)

{
  "success": true,
  "message": "Service is healthy",
  "data": {
    "status": "ok",
    "version": "0.1.0",
    "timestamp": "2025-06-04T07:59:17.404Z",
    "database": {
      "name": "rbca",
      "host": "mongodb+srv://app_dev_user_prayogrbca:****@prayogdevqa.em5uh.mongodb.net/rbca",
      "connected": true,
      "collections": ["Users", "Modules", "Services", "Tenants", "test", "APIKeys", "UserRoles", "APIs", "Roles"]
    }
  }
}

2. List Roles

Retrieves a paginated list of roles for a tenant.

GET /roles

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`test-tenant`

Example Curl Command

curl --location 'http://localhost:9021/access-roles-service/api/v1/roles' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49'

Success Response (200 OK)

{
  "success": true,
  "message": "Roles found",
  "data": {
    "items": [
      {
        "_id": "683eb9b6a5c11d9c6556bd69",
        "name": "Manager",
        "description": "Will manage",
        "tenantId": "682581255a53dbe3ffb4fe49",
        "moduleIds": [],
        "userCount": 0,
        "moduleCount": 0,
        "permissionsCount": 0
      },
      {
        "_id": "683eb949a5c11d9c6556bd57",
        "name": "Operator",
        "description": "Will operator all bookings",
        "tenantId": "682581255a53dbe3ffb4fe49",
        "moduleIds": ["68303804b5a0a90fe57f5185", "683038f3b5a0a90fe57f5187"],
        "userCount": 1,
        "moduleCount": 21,
        "permissionsCount": 21
      }
    ],
    "total": 4,
    "page": 1,
    "limit": 10,
    "totalPages": 1
  }
}

3. Create Role

Creates a new role in the specified tenant.

POST /roles

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`test-tenant`
`X-USER-ID`	Yes	User ID for audit tracking	`test-user`
`Content-Type`	Yes	Must be application/json	`application/json`

Request Body

{
  "name": "Admin",
  "description": "Administrator role with full access",
  "moduleIds": ["module1", "module2"]
}

Example Curl Command

curl --location --request POST 'http://localhost:9021/access-roles-service/api/v1/roles' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49' \
--header 'X-USER-ID: test-user' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Admin",
  "description": "Administrator role with full access",
  "moduleIds": ["module1", "module2"]
}'

Success Response (201 Created)

{
  "success": true,
  "message": "Role created successfully",
  "data": {
    "id": "683833bb76b2421e19398860",
    "name": "Admin",
    "description": "Administrator role with full access",
    "tenantId": "test-tenant",
    "moduleIds": ["module1", "module2"],
    "createdAt": "2024-04-04T11:31:09Z",
    "updatedAt": "2024-04-04T11:31:09Z"
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "message": "Validation failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data"
  }
}

409 Conflict

{
  "success": false,
  "message": "A role with this name already exists for this tenant",
  "error": {
    "code": "ROLE_ALREADY_EXISTS",
    "message": "A role with this name already exists for this tenant"
  }
}

4. Get Role Details

Retrieves details of a specific role.

GET /roles/:id

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`test-tenant`

Path Parameters

Parameter	Type	Description	Example
`id`	string	Role ID	`683833bb76b2421e19398860`

Example Curl Command

curl --location 'http://localhost:9021/access-roles-service/api/v1/roles/683eb9b6a5c11d9c6556bd69' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49'

Success Response (200 OK)

{
  "success": true,
  "message": "Role found",
  "data": {
    "_id": "683eb9b6a5c11d9c6556bd69",
    "name": "Manager",
    "description": "Will manage",
    "tenantId": "682581255a53dbe3ffb4fe49",
    "moduleIds": [],
    "userCount": 0,
    "moduleCount": 0
  }
}

Error Responses

404 Not Found

{
  "success": false,
  "message": "Role not found",
  "error": {
    "code": "NOT_FOUND",
    "message": "Role not found"
  }
}

5. Get Role Module Access

Retrieves the modules accessible to a role, grouped by service.

GET /roles/:id/modules

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`test-tenant`
`Authorization`	Yes	Bearer token	`Bearer <token>`

Path Parameters

Parameter	Type	Description	Example
`id`	string	Role ID	`683833bb76b2421e19398860`

Example Curl Command

curl --location 'http://localhost:9021/access-roles-service/api/v1/roles/683eb949a5c11d9c6556bd57/modules' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49'

Success Response (200 OK)

{
  "success": true,
  "message": "Role modules found",
  "data": [
    {
      "serviceId": "68302e7bb5a0a90fe57f5184",
      "serviceName": "Roles and Permissions",
      "modules": [
        {
          "id": "68303804b5a0a90fe57f5185",
          "name": "Create Role",
          "hasAccess": true
        },
        {
          "id": "683038f3b5a0a90fe57f5187",
          "name": "View All Roles",
          "hasAccess": true
        }
      ],
      "totalModules": 4,
      "accessModules": 4,
      "noAccessModules": 0,
      "permissionsLabel": "4 permissions",
      "hasServiceAccess": true
    }
  ]
}

Error Responses

404 Not Found

{
  "success": false,
  "message": "Role not found",
  "error": {
    "code": "NOT_FOUND",
    "message": "Role not found"
  }
}

6. Update Role

Updates an existing role’s details.

PATCH /roles/:id

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`test-tenant`
`X-USER-ID`	Yes	User ID for audit tracking	`test-user`
`Content-Type`	Yes	Must be application/json	`application/json`

Path Parameters

Parameter	Type	Description	Example
`id`	string	Role ID	`683833bb76b2421e19398860`

Request Body

{
  "name": "Manager Updated",
  "description": "Updated description for Manager"
}

Example Curl Command

curl --location --request PATCH 'http://localhost:9021/access-roles-service/api/v1/roles/683eb9b6a5c11d9c6556bd69' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49' \
--header 'X-USER-ID: test-user' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Manager Updated",
  "description": "Updated description for Manager"
}'

Success Response (200 OK)

{
  "success": true,
  "message": "Role updated successfully",
  "data": {
    "_id": "683eb9b6a5c11d9c6556bd69",
    "name": "Manager Updated",
    "description": "Updated description for Manager",
    "tenantId": "682581255a53dbe3ffb4fe49",
    "moduleIds": []
  }
}

Error Responses

404 Not Found

{
  "success": false,
  "message": "Role not found",
  "error": {
    "code": "NOT_FOUND",
    "message": "Role not found"
  }
}

409 Conflict

{
  "success": false,
  "message": "A role with this name already exists for this tenant",
  "error": {
    "code": "ROLE_ALREADY_EXISTS",
    "message": "A role with this name already exists for this tenant"
  }
}

7. Delete Role

Deletes a role from the system.

DELETE /roles/:id

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`test-tenant`
`X-USER-ID`	Yes	User ID for audit tracking	`test-user`

Path Parameters

Parameter	Type	Description	Example
`id`	string	Role ID	`683833bb76b2421e19398860`

Example Curl Command

curl --location --request DELETE 'http://localhost:9021/access-roles-service/api/v1/roles/683ffd98bd9577d534283496' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49' \
--header 'X-USER-ID: test-user'

Success Response (200 OK)

{
  "success": true,
  "message": "Role deleted successfully",
  "data": null
}

Error Responses

404 Not Found

{
  "success": false,
  "message": "Role not found",
  "error": {
    "code": "NOT_FOUND",
    "message": "Role not found"
  }
}

8. Assign Users to Role

Assigns users to a specific role.

PUT /roles/:id/users

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`test-tenant`
`X-USER-ID`	Yes	User ID for audit tracking	`test-user`
`Authorization`	Yes	Bearer token	`Bearer <token>`
`Content-Type`	Yes	Must be application/json	`application/json`

Path Parameters

Parameter	Type	Description	Example
`id`	string	Role ID	`683833bb76b2421e19398860`

Request Body

{
  "users": [
    { "userId": "user1" }
  ]
}

Example Curl Command

curl --location --request PUT 'http://localhost:9021/access-roles-service/api/v1/roles/683eb9b6a5c11d9c6556bd69/users' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49' \
--header 'X-USER-ID: test-user' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{"users":[{"userId":"user1"}]}'

Success Response (200 OK)

{
  "success": true,
  "message": "Users assigned to role successfully",
  "data": null
}

Error Responses

404 Not Found

{
  "success": false,
  "message": "Role not found",
  "error": {
    "code": "NOT_FOUND",
    "message": "Role not found"
  }
}

9. Get Users in Role

Retrieves all users assigned to a specific role.

GET /roles/:id/users

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`test-tenant`

Path Parameters

Parameter	Type	Description	Example
`id`	string	Role ID	`683833bb76b2421e19398860`

Example Curl Command

curl --location 'http://localhost:9021/access-roles-service/api/v1/roles/683eb949a5c11d9c6556bd57/users' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49'

Success Response (200 OK)

{
  "success": true,
  "message": "Users for role found successfully",
  "data": [
    {
      "_id": "51f32d0a-1011-7066-d410-60fe56133550",
      "name": "Akash Sharma",
      "username": "mockuser22@yopmail.com",
      "assignedAt": "2025-06-03T09:11:50.417Z",
      "assignedBy": "b1331d7a-a081-70ec-6c9d-a8d96203c377",
      "tenantId": "682581255a53dbe3ffb4fe49",
      "isAssigned": true
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

Response Fields

Field	Type	Description
`data[]._id`	string	User ID
`data[].name`	string	User’s full name
`data[].username`	string	User’s email/username
`data[].assignedAt`	string	ISO timestamp when the user was assigned to the role
`data[].assignedBy`	string	User ID of the person who assigned the role
`data[].tenantId`	string	Tenant ID the user belongs to
`data[].isAssigned`	boolean	Whether the user is assigned to the role
`total`	number	Total number of users found
`page`	number	Current page number
`limit`	number	Number of items per page

Error Responses

404 Not Found

{
  "success": false,
  "message": "Role not found",
  "error": {
    "code": "NOT_FOUND",
    "message": "Role not found"
  }
}

10. Check User Assignments

Checks which users are assigned to a specific role, with optional search functionality.

GET /roles/:id/users/check

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`682581255a53dbe3ffb4fe49`

Path Parameters

Parameter	Type	Description	Example
`id`	string	Role ID	`683eb949a5c11d9c6556bd57`

Query Parameters

Parameter	Required	Type	Description	Default
`search`	No	string	Search term for filtering users by name or username	-
`page`	No	integer	Page number	1
`limit`	No	integer	Items per page	10

Example Curl Command

curl --location 'http://localhost:9021/access-roles-service/api/v1/roles/683eb949a5c11d9c6556bd57/users/check' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49'

Success Response (200 OK)

{
  "success": true,
  "message": "Users for role found successfully",
  "data": [
    {
      "_id": "51f32d0a-1011-7066-d410-60fe56133550",
      "name": "Akash Sharma",
      "username": "mockuser22@yopmail.com",
      "tenantId": "682581255a53dbe3ffb4fe49",
      "isAssigned": true,
      "assignedAt": "2025-06-03T09:11:50.417Z",
      "assignedBy": "b1331d7a-a081-70ec-6c9d-a8d96203c377"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

Response Fields

Field	Type	Description
`data[]._id`	string	User ID
`data[].name`	string	User’s full name
`data[].username`	string	User’s email/username
`data[].tenantId`	string	Tenant ID the user belongs to
`data[].isAssigned`	boolean	Whether the user is assigned to the role
`data[].assignedAt`	string	ISO timestamp when the user was assigned to the role
`data[].assignedBy`	string	User ID of the person who assigned the role
`total`	number	Total number of users found
`page`	number	Current page number
`limit`	number	Number of items per page

11. Assign Roles to User

Assigns one or more roles to a user within a specific tenant context.

PUT /users/:userId/roles

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`test-tenant`
`Authorization`	Yes	Bearer token	`Bearer <token>`
`Content-Type`	Yes	Must be application/json	`application/json`

Path Parameters

Parameter	Type	Description	Example
`userId`	string	User ID to assign roles to	`b1331d7a-a081-70ec-6c9d-a8d96203c377`

Request Body

{
  "roles": [
    {
      "roleId": "683eb9b6a5c11d9c6556bd69"
    }
  ]
}

Example Curl Command

curl --location --request PUT 'http://localhost:9021/access-roles-service/api/v1/users/b1331d7a-a081-70ec-6c9d-a8d96203c377/roles' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "roles": [
    {
      "roleId": "683eb9b6a5c11d9c6556bd69"
    }
  ]
}'

Success Response (200 OK)

{
  "success": true,
  "message": "Role assigned successfully",
  "data": null
}

Error Responses

404 Not Found

{
  "success": false,
  "message": "User or role not found",
  "error": {
    "code": "NOT_FOUND",
    "message": "User or role not found"
  }
}

12. Revoke Role from User

Revokes a role from a user within a specific tenant context.

DELETE /users/:userId/roles

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`test-tenant`
`Authorization`	Yes	Bearer token	`Bearer <token>`
`Content-Type`	Yes	Must be application/json	`application/json`

Path Parameters

Parameter	Type	Description	Example
`userId`	string	User ID to revoke role from	`b1331d7a-a081-70ec-6c9d-a8d96203c377`

Request Body

{
  "roleId": "683eb9b6a5c11d9c6556bd69"
}

Example Curl Command

curl --location --request DELETE 'http://localhost:9021/access-roles-service/api/v1/users/b1331d7a-a081-70ec-6c9d-a8d96203c377/roles' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "roleId": "683eb9b6a5c11d9c6556bd69"
}'

Success Response (200 OK)

{
  "success": true,
  "message": "Role revoked successfully",
  "data": null
}

Error Responses

404 Not Found

{
  "success": false,
  "message": "User or role not found",
  "error": {
    "code": "NOT_FOUND",
    "message": "User or role not found"
  }
}

13. Get User’s Roles

Retrieves all roles assigned to a user, with optional filtering by tenant.

GET /users/:userId/roles

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`682581255a53dbe3ffb4fe49`

Path Parameters

Parameter	Type	Description	Example
`userId`	string	User ID to get roles for	`51f32d0a-1011-7066-d410-60fe56133550`

Query Parameters

Parameter	Required	Type	Description	Default
`tenantId`	No	string	Filter roles by tenant ID	-

Example Curl Command

curl --location 'http://localhost:9021/access-roles-service/api/v1/users/51f32d0a-1011-7066-d410-60fe56133550/roles' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49'

Success Response (200 OK)

{
  "success": true,
  "message": "User roles found",
  "data": [
    {
      "userId": "51f32d0a-1011-7066-d410-60fe56133550",
      "roleId": "683eb949a5c11d9c6556bd57",
      "tenantId": "682581255a53dbe3ffb4fe49",
      "assignedAt": "2025-06-03T09:11:50.417Z",
      "assignedBy": "b1331d7a-a081-70ec-6c9d-a8d96203c377",
      "role": {
        "name": "Operator",
        "description": "Will operator all bokings",
        "moduleIds": [
          "68303804b5a0a90fe57f5185",
          "683038f3b5a0a90fe57f5187"
        ]
      }
    }
  ]
}

Response Fields

Field	Type	Description
`data[].userId`	string	User ID
`data[].roleId`	string	Role ID
`data[].tenantId`	string	Tenant ID
`data[].assignedAt`	string	ISO timestamp when the role was assigned
`data[].assignedBy`	string	User ID of the person who assigned the role
`data[].role.name`	string	Name of the role
`data[].role.description`	string	Description of the role
`data[].role.moduleIds`	string[]	Array of module IDs the role has access to

14. Get User’s Module Access

Retrieves a user’s effective module access based on their assigned roles, grouped by service.

GET /users/modules

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`test-tenant`
`X-USER-ID`	Yes	User ID to get module access for	`b1331d7a-a081-70ec-6c9d-a8d96203c377`

Example Curl Command

curl --location 'http://localhost:9021/access-roles-service/api/v1/users/modules' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49' \
--header 'X-USER-ID: b1331d7a-a081-70ec-6c9d-a8d96203c377'

Success Response (200 OK)

{
  "success": true,
  "message": "User modules found",
  "data": [
    {
      "serviceId": "68302e7bb5a0a90fe57f5184",
      "serviceName": "Roles and Permissions",
      "modules": [
        {
          "id": "68303804b5a0a90fe57f5185",
          "name": "Create Role",
          "hasAccess": true
        },
        {
          "id": "683038f3b5a0a90fe57f5187",
          "name": "View All Roles",
          "hasAccess": true
        }
      ],
      "totalModules": 4,
      "accessModules": 4,
      "noAccessModules": 0,
      "permissionsLabel": "4 permissions",
      "hasServiceAccess": true
    }
  ]
}

Error Responses

404 Not Found

{
  "success": false,
  "message": "User not found",
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found"
  }
}

15. Search User Tenant Access

Searches for users and retrieves their tenant access information using specific search criteria.

GET /users/search/tenants

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`test-tenant`

Query Parameters

Parameter	Required	Type	Description	Example
`email`	No*	string	Search by user’s email	`cabob21438@hazhab.com`
`mobile`	No*	string	Search by user’s mobile number	-
`username`	No*	string	Search by username	-
`userId`	No*	string	Search by user ID	-

*At least one search parameter must be provided

Example Curl Command

curl --location 'http://localhost:9021/access-roles-service/api/v1/users/search/tenants?email=cabob21438@hazhab.com' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49'

Success Response (200 OK)

{
  "success": true,
  "message": "User tenant access retrieved successfully",
  "data": {
    "userId": "b1331d7a-a081-70ec-6c9d-a8d96203c377",
    "totalTenants": 1,
    "tenants": [
      {
        "tenantId": "682581255a53dbe3ffb4fe49",
        "tenantName": "Quick Couriers"
      }
    ]
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "message": "At least one search criteria must be provided (email, mobile, username, or userId)",
  "error": {
    "code": "BAD_REQUEST",
    "message": "At least one search criteria must be provided (email, mobile, username, or userId)"
  }
}

404 Not Found

{
  "success": false,
  "message": "User not found",
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found"
  }
}

16. Get User’s Tenant Access

Retrieves all users and their tenant access information for the specified tenant.

GET /users/tenant

Headers

Header	Required	Description	Example
`X-TENANT-ID`	Yes	Tenant ID	`test-tenant`

Example Curl Command

curl --location 'http://localhost:9021/access-roles-service/api/v1/users/tenant' \
--header 'X-TENANT-ID: 682581255a53dbe3ffb4fe49'

Success Response (200 OK)

{
  "success": true,
  "message": "Users found successfully",
  "data": [
    {
      "_id": "b1331d7a-a081-70ec-6c9d-a8d96203c377",
      "name": "Quick Courier Test Admin",
      "username": "cabob21438@hazhab.com",
      "tenantAccess": [
        {
          "tenantId": "682581255a53dbe3ffb4fe49",
          "accessModules": [],
          "role": "user"
        }
      ],
      "createdOn": 1747305013996,
      "updatedOn": 1747305013996
    }
  ],
  "total": 3,
  "page": 1,
  "limit": 10
}

Error Responses

404 Not Found

{
  "success": false,
  "message": "Tenant not found",
  "error": {
    "code": "NOT_FOUND",
    "message": "Tenant not found"
  }
}

Common Error Responses

View All Common Error Responses

400 Bad Request

{
  "success": false,
  "message": "Invalid input data",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data"
  }
}

404 Not Found

{
  "success": false,
  "message": "Resource not found",
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

409 Conflict

{
  "success": false,
  "message": "Resource already exists",
  "error": {
    "code": "CONFLICT",
    "message": "Resource already exists"
  }
}

503 Service Unavailable

{
  "success": false,
  "message": "Service unavailable",
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service is currently unavailable"
  }
}