ReferenceAdmin Centre API

Roles & permissions

Roles bundle permissions. Built-in roles (Global Administrator, RMM Technician, PSA Admin…) can't be changed; organisations can create custom roles from the permission catalogue and give them to people.

Method	Path	Summary
GET	`/v1/admin/tenant/applications`	List the platform-wide application catalog
GET	`/v1/admin/tenant/permissions`	List the full platform permission catalog
GET	`/v1/admin/tenant/roles`	List all roles with their application and assigned-user count
GET	`/v1/admin/tenant/roles/:id`	Get a role with its full permission checklist
GET	`/v1/admin/tenant/roles/:id/members`	List the users in this tenant who hold a role
POST	`/v1/admin/tenant/roles/:id/members`	Give a user in this tenant a role
DELETE	`/v1/admin/tenant/roles/:id/members/:userId`	Take a role away from a user in this tenant
POST	`/v1/admin/tenant/roles`	Create a custom role
PATCH	`/v1/admin/tenant/roles/:id`	Update a custom role's description and permissions
DELETE	`/v1/admin/tenant/roles/:id`	Delete a custom role

#List the platform-wide application catalog

GET/v1/admin/tenant/applications

List the platform-wide application catalog. Requires the GLOBAL_ADMIN role. Not filtered to what this tenant has licensed — used to populate the "which app does this role apply to" dropdown when creating a role.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/applications
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Response 200

Field	Type	Description
`applications`	array of object
`applications[].id`	integer
`applications[].name`	string
`applications[].logo`	string

Example response

JSON

{
  "applications": [
    {
      "id": 42,
      "name": "Example name",
      "logo": "string"
    }
  ]
}

Example request

Bash

curl -X GET 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/applications' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/applications', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.get(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/applications",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method GET -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/applications' -Headers $headers

#List the full platform permission catalog

GET/v1/admin/tenant/permissions

List the full platform permission catalog. Requires the GLOBAL_ADMIN role. Global, not per-tenant. Used to render a checklist when creating a new role, before it has any granted permissions of its own.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/permissions
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Response 200

Field	Type	Description
`permissions`	array of object
`permissions[].id`	integer
`permissions[].slug`	string
`permissions[].display_name`	string
`permissions[].description`	string, or null
`permissions[].application_id`	integer, or null
`permissions[].category`	string, or null

Example response

JSON

{
  "permissions": [
    {
      "id": 42,
      "slug": "example",
      "display_name": "Example display name",
      "description": "string",
      "application_id": 7,
      "category": "string"
    }
  ]
}

Example request

Bash

curl -X GET 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/permissions' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/permissions', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.get(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/permissions",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method GET -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/permissions' -Headers $headers

#List all roles with their application and assigned-user count

GET/v1/admin/tenant/roles

List all roles with their application and assigned-user count. Requires the GLOBAL_ADMIN role.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Response 200

Field	Type	Description
`roles`	array of object
`roles[].id`	integer
`roles[].slug`	string
`roles[].display_name`	string
`roles[].description`	string, or null
`roles[].application_id`	integer, or null
`roles[].application_name`	string
`roles[].is_system`	boolean
`roles[].user_count`	boolean

Example response

JSON

{
  "roles": [
    {
      "id": 42,
      "slug": "example",
      "display_name": "Example display name",
      "description": "string",
      "application_id": 7,
      "application_name": "Example application name",
      "is_system": true,
      "user_count": false
    }
  ]
}

Example request

Bash

curl -X GET 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.get(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method GET -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles' -Headers $headers

#Get a role with its full permission checklist

GET/v1/admin/tenant/roles/:id

Get a role with its full permission checklist. Requires the GLOBAL_ADMIN role. Returns every permission applicable to the role's application (or global permissions if application_id is null), each flagged with whether it's currently granted.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/:id
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Field	Type	Description
`role`	any
`permissions`	array of any

Example response

JSON

{
  "role": null,
  "permissions": []
}

Errors

Status	Message
404	Role not found

Example request

Bash

curl -X GET 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.get(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method GET -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42' -Headers $headers

#List the users in this tenant who hold a role

GET/v1/admin/tenant/roles/:id/members

List the users in this tenant who hold a role. Requires the GLOBAL_ADMIN role.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/:id/members
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Field	Type	Description
`members`	array of any

Example response

JSON

{
  "members": []
}

Example request

Bash

curl -X GET 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42/members' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42/members', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.get(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42/members",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method GET -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42/members' -Headers $headers

#Give a user in this tenant a role

POST/v1/admin/tenant/roles/:id/members

Give a user in this tenant a role. Requires the GLOBAL_ADMIN role. Idempotent.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/:id/members
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Path parameters

Name	Type	Description
`id`required	integer

Request body JSON

Name	Type	Description
`user_id`	integer

Response 200

Field	Type	Description
`success`	boolean

Example response

JSON

{
  "success": true
}

Errors

Status	Message
404	Role not found
404	User not found

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42/members' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":7}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42/members', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"user_id":7}),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42/members",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"user_id":7},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"user_id":7}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42/members' -Headers $headers -ContentType 'application/json' -Body $body

#Take a role away from a user in this tenant

DELETE/v1/admin/tenant/roles/:id/members/:userId

Take a role away from a user in this tenant. Requires the GLOBAL_ADMIN role. Refuses to remove the tenant's last Global Administrator, or your own Global Administrator role.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/:id/members/:userId
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Path parameters

Name	Type	Description
`id`required	integer
`userId`required	number

Response 200

Field	Type	Description
`success`	boolean

Example response

JSON

{
  "success": true
}

Errors

Status	Message
404	Role not found
404	User not found
409	You can't remove your own Global Administrator role. Ask another Global Administrator.
409	This is the organisation's only Global Administrator.

Example request

Bash

curl -X DELETE 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42/members/12.5' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42/members/12.5', {
  method: 'DELETE',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.delete(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42/members/12.5",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method DELETE -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42/members/12.5' -Headers $headers

#Create a custom role

POST/v1/admin/tenant/roles

Create a custom role. Requires the GLOBAL_ADMIN role. slug is auto-derived from display_name (uppercased, non-alphanumerics collapsed to underscores). New roles are always is_system=0.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Request body JSON

Name	Type	Description
`display_name`required	string	The role's name.
`description`	string	What the role is for.
`application_id`	string	The app the role belongs to (optional).
`permission_ids`	array of any	Permission ids from `GET /v1/admin/tenant/permissions`.

Response 201

Field	Type	Description
`success`	boolean
`role`	object
`role.id`	integer
`role.slug`	string
`role.display_name`	string

Example response

JSON

{
  "success": true,
  "role": {
    "id": 42,
    "slug": "example",
    "display_name": "Example display name"
  }
}

Errors

Status	Message
400	display_name is required
400	display_name must contain at least one letter or number
409	A role with that name already exists

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"Example display name","description":"string","application_id":"string","permission_ids":[]}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"display_name":"Example display name","description":"string","application_id":"string","permission_ids":[]}),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"display_name":"Example display name","description":"string","application_id":"string","permission_ids":[]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"display_name":"Example display name","description":"string","application_id":"string","permission_ids":[]}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles' -Headers $headers -ContentType 'application/json' -Body $body

#Update a custom role's description and permissions

PATCH/v1/admin/tenant/roles/:id

Update a custom role's description and permissions. Requires the GLOBAL_ADMIN role. System roles (GLOBAL_ADMIN/USER/RMM_ADMIN) cannot be edited.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/:id
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Path parameters

Name	Type	Description
`id`required	integer

Request body JSON

Name	Type	Description
`display_name`	string
`description`	string
`permission_ids`	array of any

Response 200

Field	Type	Description
`success`	boolean

Example response

JSON

{
  "success": true
}

Errors

Status	Message
404	Role not found
403	Built-in roles can't be edited. Create a custom role instead.

Example request

Bash

curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"Example display name","description":"string","permission_ids":[]}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42', {
  method: 'PATCH',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"display_name":"Example display name","description":"string","permission_ids":[]}),
});
const data = await res.json();

Python

import os, requests

r = requests.patch(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"display_name":"Example display name","description":"string","permission_ids":[]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"display_name":"Example display name","description":"string","permission_ids":[]}'
Invoke-RestMethod -Method PATCH -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42' -Headers $headers -ContentType 'application/json' -Body $body

#Delete a custom role

DELETE/v1/admin/tenant/roles/:id

Delete a custom role. Requires the GLOBAL_ADMIN role. System roles cannot be deleted. If users currently hold the role, the request is rejected unless force=true is passed.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/:id
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Role: GLOBAL_ADMIN.

Path parameters

Name	Type	Description
`id`required	integer

Query parameters

Name	Type	Description
`force`	string

Response 200

Field	Type	Description
`success`	boolean

Example response

JSON

{
  "success": true
}

Errors

Status	Message
404	Role not found
403	Built-in roles can't be deleted
409	… user(s) currently hold this role. Reassign them first, or pass ?force=true to delete anyway.

Example request

Bash

curl -X DELETE 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42', {
  method: 'DELETE',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.delete(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method DELETE -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/roles/42' -Headers $headers

Was this page helpful?