POST/api/v1/create-role-for-org

Create a role

Creates a named role in one workspace together with its spending limit and reset cycle, and returns the role id to assign it with.

AccessRequires a permission in the workspaceMANAGE_PERMS

A role is a named bundle of permissions held by a member inside a single workspace. This call creates the role and its spending policy in one request; the permissions are attached separately with POST /api/v1/add-perm-to-role. Once the role exists, give it to a member with POST /api/v1/change-user-role.

Roles are workspace-scoped. A role created in this workspace grants nothing in any other workspace, even inside the same organisation, so a member who works across two workspaces needs a role in each. For how roles are meant to be structured, see Roles and permissions.

The Owner role is not created here

The Owner role is created with the organisation, bypasses all permission checks, and cannot be created, modified, or assigned manually. Every role you create with this endpoint is a normal role subject to permission checks.

Body parameters

workspace_idnumberrequired

The workspace the role belongs to. The role exists only in this workspace.

role_namestringrequired

Display name for the role, shown wherever members and roles are listed.

role_descstringrequired

Short description of what the role is for.

org_uidnumberrequired

The organisation the workspace belongs to.

new_transaction_limitstringrequired

The role's spending limit for one cycle, as a decimal string.

cycle_periodstringrequired

How often the role's usage counter resets. W for weekly or M for monthly.

cycle_daynumberrequired

The day the counter resets. Day of the week for a weekly cycle, day of the month for a monthly cycle.

bash

curl -X POST "$SQRL_API/api/v1/create-role-for-org" \
  -H "authorization: Bearer $SQRL_TOKEN" \
  -H "content-type: application/json" \
  -d '{
        "workspace_id": 342,
        "role_name": "Settlement approver",
        "role_desc": "Signs settlement movements up to the desk limit",
        "org_uid": 118,
        "new_transaction_limit": "50000.00",
        "cycle_period": "M",
        "cycle_day": 1
      }'

const res = await fetch(`${process.env.SQRL_API}/api/v1/create-role-for-org`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.SQRL_TOKEN}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    workspace_id: 342,
    role_name: "Settlement approver",
    role_desc: "Signs settlement movements up to the desk limit",
    org_uid: 118,
    new_transaction_limit: "50000.00",
    cycle_period: "M",
    cycle_day: 1,
  }),
});
const { Success, UID } = await res.json();

rust

let res = client
    .post(format!("{}/api/v1/create-role-for-org", api_base))
    .bearer_auth(&token)
    .json(&serde_json::json!({
        "workspace_id": 342,
        "role_name": "Settlement approver",
        "role_desc": "Signs settlement movements up to the desk limit",
        "org_uid": 118,
        "new_transaction_limit": "50000.00",
        "cycle_period": "M",
        "cycle_day": 1,
    }))
    .send()
    .await?;

Response200 OK

{
"Success": true,
"UID": 79
}

#What happens next

UID is the new role id. Use it as role_uid when granting permissions with POST /api/v1/add-perm-to-role, as role_id when adjusting the policy with POST /api/v1/update-role-policies, and as role_id when assigning the role to a member. A role with no permissions granted to it carries a spending limit but no rights in the workspace, so grant its permissions before you hand it to anyone.

Was this page helpful?