Roles

The following endpoints retrieve the mapping of a userRoleId parameter and user role name, and let you create, update, and delete custom organization and team roles.

Create a custom role

post

/users/custom-roles

Creates a new custom organization or team role. Requires the organization custom roles edit permission on the organization.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Authorize the API call with your API token in the Authorization header with the value: Token your-api-token.

If you don't have an API token yet, please refer to the "Authentication" section to learn how to create one.

Body

namestring · min: 1 · max: 50Required

The name of the custom role.

Example: Custom Viewer

permissionTypestring · enumRequired

Whether the role applies to the organization or a team.

Example: organizationPossible values:

organizationIdintegerRequired

The ID of the organization to create the custom role in.

Example: 1

descriptionstring · nullableOptional

An optional description of the custom role.

Example: Read-only access to organization resources.

permissionsinteger[]Optional

List of permission IDs to assign to the custom role.

Example: [101,102]

Responses

200

Successful response

application/json

post/users/custom-roles

POST /api/v2/users/custom-roles HTTP/1.1
Host: eu1.make.com
Authorization: Token your-api-token
Content-Type: application/json
Accept: */*
Content-Length: 159

{
  "name": "Custom Viewer",
  "permissionType": "organization",
  "organizationId": 1,
  "description": "Read-only access to organization resources.",
  "permissions": [
    101,
    102
  ]
}

200

Successful response

{
  "role": {
    "id": 42,
    "name": "Custom Viewer",
    "category": "organization",
    "managementType": "custom_managed",
    "description": "Read-only access to organization resources.",
    "permissions": [
      {
        "id": 101,
        "name": "scenarios get"
      },
      {
        "id": 102,
        "name": "scenario view"
      }
    ]
  }
}

Delete a custom role

delete

/users/custom-roles

Deletes an existing custom role. Only custom-managed roles can be deleted. The role must not be currently assigned to any users.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Authorize the API call with your API token in the Authorization header with the value: Token your-api-token.

If you don't have an API token yet, please refer to the "Authentication" section to learn how to create one.

Body

idintegerRequired

The ID of the custom role to delete.

Example: 42

organizationIdintegerRequired

The ID of the organization the custom role belongs to.

Example: 1

Responses

200

Successful response

application/json

roleIdintegerOptional

The ID of the deleted custom role.

delete/users/custom-roles

DELETE /api/v2/users/custom-roles HTTP/1.1
Host: eu1.make.com
Authorization: Token your-api-token
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "id": 42,
  "organizationId": 1
}

200

Successful response

{
  "roleId": 42
}

Update a custom role

patch

/users/custom-roles

Updates the name, description, or permissions of an existing custom role. Only custom-managed roles can be updated.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Authorize the API call with your API token in the Authorization header with the value: Token your-api-token.

If you don't have an API token yet, please refer to the "Authentication" section to learn how to create one.

Body

idintegerRequired

The ID of the custom role to update.

Example: 42

organizationIdintegerRequired

The ID of the organization the custom role belongs to.

Example: 1

namestring · min: 1 · max: 50Optional

New name for the custom role.

Example: Updated Viewer

descriptionstring · nullableOptional

New description for the custom role. Pass null to clear it.

Example: Updated description.

permissionsinteger[]Optional

Full list of permission IDs to assign to the role. Replaces existing permissions.

Example: [101]

Responses

200

Successful response

application/json

patch/users/custom-roles

PATCH /api/v2/users/custom-roles HTTP/1.1
Host: eu1.make.com
Authorization: Token your-api-token
Content-Type: application/json
Accept: */*
Content-Length: 109

{
  "id": 42,
  "organizationId": 1,
  "name": "Updated Viewer",
  "description": "Updated description.",
  "permissions": [
    101
  ]
}

200

Successful response

{
  "role": {
    "id": 42,
    "name": "Updated Viewer",
    "category": "organization",
    "managementType": "custom_managed",
    "description": "Updated description.",
    "permissions": [
      {
        "id": 101,
        "name": "scenarios get"
      }
    ]
  }
}

User role definitions

get

/users/roles

Gets list of all existing user role names and IDs. Optionally filter by category, a specific roleId, or pass organizationId/teamId to include custom roles for that organization. Set the user roles in an organization with the POST /users/{userId}/user-organization-roles/{organizationId} API call. Use the POST /users/{userId}/user-team-roles/{teamId} API call to set user roles in a team.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Authorize the API call with your API token in the Authorization header with the value: Token your-api-token.

If you don't have an API token yet, please refer to the "Authentication" section to learn how to create one.

Query parameters

categorystring · enumOptional

Set this parameter to organization or team to get user roles in an organization or in a team.

Example: teamPossible values:

organizationIdintegerOptional

Include custom roles belonging to this organization. Can be combined with teamId; if both are provided and the team does not belong to the organization, the request returns 400. If the organization does not have the customRoles license, or the caller lacks permission to view that organization's users, custom roles are silently excluded from the response while the system roles are still returned.

Example: 1

teamIdintegerOptional

Include custom roles belonging to the organization that owns this team. Can be combined with organizationId; if both are provided and the team does not belong to the organization, the request returns 400. If the organization does not have the customRoles license, or the caller lacks permission to view that organization's users, custom roles are silently excluded from the response while the system roles are still returned.

Example: 1

roleIdintegerOptional

Filter the response to a single role by its ID.

Example: 42

excludeRole[]integer[]Optional

Exclude roles with these IDs from the response.

Example: [1,3]

Responses

200

Successful response

application/json

400

Bad request. Returned when organizationId and teamId are both provided and the team does not belong to the specified organization.

get/users/roles

GET /api/v2/users/roles HTTP/1.1
Host: eu1.make.com
Authorization: Token your-api-token
Accept: */*

{
  "usersRoles": [
    {
      "id": 1,
      "name": "Team Admin"
    },
    {
      "id": 3,
      "name": "Team Member"
    },
    {
      "id": 4,
      "name": "Team Monitoring"
    },
    {
      "id": 6,
      "name": "Team Operator"
    },
    {
      "id": 11,
      "name": "Owner"
    },
    {
      "id": 12,
      "name": "Admin"
    },
    {
      "id": 13,
      "name": "Member"
    },
    {
      "id": 14,
      "name": "Accountant"
    }
  ]
}

Get role detail

get

/users/roles/{roleId}

Returns the detail of a single role by its ID. For custom-managed roles, requires the customRoles license and ORGANIZATION_USERS_VIEW permission on the role's organization.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Authorize the API call with your API token in the Authorization header with the value: Token your-api-token.

If you don't have an API token yet, please refer to the "Authentication" section to learn how to create one.

Path parameters

roleIdintegerRequired

The ID of the role.

Example: 42

Responses

200

Successful response

application/json

400

Not available on self-hosted (private) deployments.

403

Insufficient rights or the organization does not have the customRoles license.

404

Role not found.

get/users/roles/{roleId}

GET /api/v2/users/roles/{roleId} HTTP/1.1
Host: eu1.make.com
Authorization: Token your-api-token
Accept: */*

{
  "usersRole": {
    "id": 42,
    "name": "Custom Viewer",
    "identifier": "custom_viewer",
    "category": "organization",
    "subsidiary": true,
    "managementType": "custom_managed",
    "description": "Read-only access to organization resources.",
    "organizationId": 1,
    "permissions": [
      "scenario view",
      "scenario start"
    ]
  }
}

User role permission definitions

get

/users/roles/permissions

Gets a list of all available permissions that can be assigned to user roles. Use the roleCategory parameter to filter permissions by team or organization roles.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Authorize the API call with your API token in the Authorization header with the value: Token your-api-token.

If you don't have an API token yet, please refer to the "Authentication" section to learn how to create one.

Query parameters

roleCategorystring · enumOptional

Filter permissions by role category. Use team for team role permissions or organization for organization role permissions.

Example: teamPossible values:

Responses

200

Successful response

application/json

get/users/roles/permissions

GET /api/v2/users/roles/permissions HTTP/1.1
Host: eu1.make.com
Authorization: Token your-api-token
Accept: */*

200

Successful response

{
  "usersRolesPermissions": [
    {
      "id": 1,
      "name": "account add",
      "note": "",
      "category": "accounts",
      "roleCategory": "team",
      "label": "",
      "customRolesHidden": false,
      "requires": []
    },
    {
      "id": 2,
      "name": "account delete",
      "note": "",
      "category": "accounts",
      "roleCategory": "team",
      "label": "",
      "customRolesHidden": false,
      "requires": []
    },
    {
      "id": 3,
      "name": "account edit",
      "note": "",
      "category": "accounts",
      "roleCategory": "team",
      "label": "",
      "customRolesHidden": false,
      "requires": [
        4
      ]
    },
    {
      "id": 4,
      "name": "accounts get",
      "note": "",
      "category": "accounts",
      "roleCategory": "team",
      "label": "",
      "customRolesHidden": false,
      "requires": []
    }
  ]
}

PreviousUser organization roles NextUnread notifications

Last updated 1 hour ago