Create a custom team role in Shogun

Create a custom role with a specific set of permissions on your Shogun account. Assign the role to team members to control what they can access.

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.

Show permission_data item fields

code · string · required

The permission code string.

has_authority · boolean

Whether the permission carries an explicit authority. Defaults to false.

authority · string

The authority string, if applicable.

reviewer_role_id · string (UUID)

The role ID of the reviewer in a Maker-Checker flow.

authorizer_role_id · string (UUID)

The role ID of the final authorizer in a Maker-Checker flow.

has_limit · boolean

Whether this permission enforces a monetary limit. Defaults to false.

limit · string (decimal)

The monetary limit to enforce. Defaults to "0.00".

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"]
  }'