Skip to main content
Use this endpoint to define a new custom role on your Shogun account. You specify the role’s name, an optional description, and the set of permissions it should carry. Once created, you can assign the role to team members when you invite them or when you update an existing member’s role. Use Fetch Permissions to obtain the permission codes you need.

​
Endpoint

POST /api/v1/auth/web/create_role

​
Authentication

This endpoint requires a valid Dashboard JWT. Pass the token in the Authorization header: 
Authorization: Bearer <access_token>

​
Request Body

​
name
string
required
A descriptive name for the role (e.g. Finance Manager, Operations Viewer). Maximum 255 characters.
​
description
string
An optional explanation of what this role is intended for. Defaults to an empty string.
​
permission_codes
array
required
An array of permission code strings to attach to this role (e.g. ["transfer.initiate", "account.view"]). Use Fetch Permissions to get valid codes.
​
permission_data
array
An optional array of detailed permission objects that include Maker-Checker metadata such as reviewer and authorizer roles, limits, and authority flags. Use this when you need fine-grained control over approval workflows.

​
Response

{
  "status": true,
  "response_code": "00",
  "message": "Role created successfully",
  "data": {
    "id": "r1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Finance Manager",
    "description": "Can initiate and approve transfers up to the defined limit.",
    "permissions": [
      {
        "code": "transfer.initiate",
        "name": "Initiate Transfer"
      }
    ],
    "created_at": "2026-04-28T12:00:00Z"
  }
}

​
Example

curl -X POST https://baasapi.payrepmfb.com/api/v1/auth/web/create_role \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Finance Manager",
    "description": "Can initiate and approve transfers up to the defined limit.",
    "permission_codes": ["transfer.initiate", "account.view"]
  }'