ReferenceAdmin Centre API

People

Staff accounts: create, edit, turn off and delete people; their username and email aliases, mailbox, groups, roles and licences; reset passwords and two-step sign-in; sign someone out everywhere. A person's username is their email address on one of the organisation's verified domains.

Method	Path	Summary
GET	`/v1/admin/tenant/users`	List people
POST	`/v1/admin/tenant/users/:id/revoke-sessions`	Sign a person out everywhere
GET	`/v1/admin/tenant/subjects/users`	Find people (for pickers)
GET	`/v1/admin/tenant/subjects/groups`	Find groups (for pickers)
POST	`/v1/admin/user/check-email`	Is this address free?
POST	`/v1/admin/user`	Create a person
POST	`/v1/admin/tenant/user`	Get a person
PUT	`/v1/admin/tenant/users/:id/picture`	Set a person's photo
DELETE	`/v1/admin/tenant/users/:id/picture`	Remove a person's photo
PATCH	`/v1/admin/tenant/user`	Change one field on a person
PATCH	`/v1/admin/user/profile`	Update a person's name details
PATCH	`/v1/admin/user/account`	Update a person's account
GET	`/v1/admin/user/addresses`	A person's username and aliases
PATCH	`/v1/admin/user/username`	Change a person's username
POST	`/v1/admin/user/aliases`	Add an email alias
DELETE	`/v1/admin/user/aliases/:id`	Remove an email alias
PATCH	`/v1/admin/user/mailbox`	Change a person's mailbox
PATCH	`/v1/admin/user/groups`	Set a person's groups
PATCH	`/v1/admin/user/roles`	Set a person's roles
PATCH	`/v1/admin/user/licenses`	Set a person's licences
PATCH	`/v1/admin/user/security`	Reset a person's password
POST	`/v1/admin/user/mfa/reset`	Reset a person's two-step sign-in
DELETE	`/v1/admin/user`	Delete a person

#List people

GET/v1/admin/tenant/users

Every staff account in the organisation, with their roles.

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

Response 200

Field	Type	Description
`users`	array of any

Example response

JSON

{
  "users": []
}

Example request

Bash

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

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/users', {
  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/users",
    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/users' -Headers $headers

#Sign a person out everywhere

POST/v1/admin/tenant/users/:id/revoke-sessions

Sign a user out everywhere. GLOBAL_ADMIN only. Deletes every Bramble Cloud session for the user.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/users/:id/revoke-sessions
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
`success`	boolean
`revoked`	integer

Example response

JSON

{
  "success": true,
  "revoked": 1
}

Errors

Status	Message
404	User not found

Example request

Bash

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

JavaScript

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

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/users/42/revoke-sessions",
    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 POST -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/users/42/revoke-sessions' -Headers $headers

#Find people (for pickers)

GET/v1/admin/tenant/subjects/users

Search the tenant's users for use as a subject picker (security policies, OIDC access, groups). Requires the GLOBAL_ADMIN role. Matches first/last/display name or email, limited to 50 results.

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

Query parameters

Name	Type	Description
`q`	any

Response 200

Field	Type	Description
`users`	array of object
`users[].id`	integer
`users[].label`	any
`users[].email`	string

Example response

JSON

{
  "users": [
    {
      "id": 42,
      "label": null,
      "email": "alex@example.com"
    }
  ]
}

Example request

Bash

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

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/subjects/users', {
  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/subjects/users",
    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/subjects/users' -Headers $headers

#Find groups (for pickers)

GET/v1/admin/tenant/subjects/groups

Search the tenant's groups for use as a subject picker (security policies, OIDC access). Requires the GLOBAL_ADMIN role. Matches group name, limited to 50 results.

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

Query parameters

Name	Type	Description
`q`	any

Response 200

Field	Type	Description
`groups`	array of object
`groups[].id`	integer
`groups[].label`	string

Example response

JSON

{
  "groups": [
    {
      "id": 42,
      "label": "Example label"
    }
  ]
}

Example request

Bash

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

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/subjects/groups', {
  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/subjects/groups",
    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/subjects/groups' -Headers $headers

#Is this address free?

POST/v1/admin/user/check-email

Checks an address before creating or renaming someone.

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

Request body JSON

Name	Type	Description
`local_part`required	string	The part before the @.
`domain`required	string	One of the organisation's verified domains.
`exclude_user_id`	any	When renaming, the person being renamed.

Response 200

Field	Type	Description
`available`	boolean
`email`	string
`message`	string

Example response

JSON

{
  "available": false,
  "email": "alex@example.com",
  "message": "Saved"
}

Errors

Status	Message
400	local_part and domain are required
404	Admin user not found

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/admin/user/check-email' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"local_part":"string","domain":"string","exclude_user_id":"…"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/user/check-email', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"local_part":"string","domain":"string","exclude_user_id":"…"}),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/api/v1/admin/user/check-email",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"local_part":"string","domain":"string","exclude_user_id":"…"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"local_part":"string","domain":"string","exclude_user_id":"…"}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/user/check-email' -Headers $headers -ContentType 'application/json' -Body $body

#Create a person

POST/v1/admin/user

Creates a staff account. The username (email) must be on one of the organisation's verified domains. Roles, licences and groups can be given at the same time. Needs Global Administrator.

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

Request body JSON

Name	Type	Description
`first_name`	string	First name.
`last_name`	string	Last name.
`display_name`	string	How their name is shown.
`email`required	string	Their username: an address on a verified domain, e.g. `alex@example.com`.
`recovery_email`	string	A personal address for password resets.
`department`	any
`job_title`	string
`location`	any
`password`required	any	Their first password.
`roles`	array of any	Role slugs to give them, e.g. `["RMM_TECHNICIAN"]`.
`package_ids`	array of any	Licence package ids to assign.
`group_ids`	array of any	Group ids to add them to.

Response 201

Field	Type	Description
`success`	boolean
`message`	string
`user_id`	integer

Example response

JSON

{
  "success": true,
  "message": "Saved",
  "user_id": 7
}

Errors

Status	Message
400	email and password are required
400	Invalid email format
400	Username can only contain letters, numbers, dots, underscores and hyphens
400	Selected domain is not verified for this tenant
404	Admin user not found
409	A user with this email already exists

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/admin/user' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Alex","last_name":"Morgan","display_name":"Example display name","email":"alex@example.com","recovery_email":"alex@example.com","department":"…","job_title":"Example job title","location":"…","password":"…","roles":[],"package_ids":[],"group_ids":[]}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/user', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"first_name":"Alex","last_name":"Morgan","display_name":"Example display name","email":"alex@example.com","recovery_email":"alex@example.com","department":"…","job_title":"Example job title","location":"…","password":"…","roles":[],"package_ids":[],"group_ids":[]}),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/api/v1/admin/user",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"first_name":"Alex","last_name":"Morgan","display_name":"Example display name","email":"alex@example.com","recovery_email":"alex@example.com","department":"…","job_title":"Example job title","location":"…","password":"…","roles":[],"package_ids":[],"group_ids":[]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"first_name":"Alex","last_name":"Morgan","display_name":"Example display name","email":"alex@example.com","recovery_email":"alex@example.com","department":"…","job_title":"Example job title","location":"…","password":"…","roles":[],"package_ids":[],"group_ids":[]}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/user' -Headers $headers -ContentType 'application/json' -Body $body

#Get a person

POST/v1/admin/tenant/user

One person's full profile, groups and licences. (A POST because it takes user_id in the body.)

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

Request body JSON

Name	Type	Description
`user_id`	integer

Response 200

Field	Type	Description
`user`	object
`user.groups`	array of object
`user.groups[].id`	integer
`user.groups[].group_name`	string
`user.licenses`	array of object
`user.licenses[].tenant_package_id`	integer
`user.licenses[].package_id`	integer
`user.licenses[].seats`	integer
`user.licenses[].expires_at`	string (date-time), or null
`user.licenses[].acquired_at`	string (date-time)
`user.licenses[].is_active`	boolean
`user.licenses[].package_name`	string
`user.licenses[].package_description`	string, or null
`user.licenses[].applications`	object

Example response

JSON

{
  "user": {
    "…tenantUser": "…",
    "groups": [
      {
        "id": 42,
        "group_name": "Example group name"
      }
    ],
    "licenses": [
      {
        "tenant_package_id": 7,
        "package_id": 7,
        "seats": 1,
        "expires_at": "2026-11-12T09:30:00.000Z",
        "acquired_at": "2026-11-12T09:30:00.000Z",
        "is_active": true,
        "package_name": "Example package name",
        "package_description": "string",
        "applications": {}
      }
    ]
  }
}

Errors

Status	Message
404	User not found
404	No user found

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/user' \
  -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/user', {
  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/user",
    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/user' -Headers $headers -ContentType 'application/json' -Body $body

#Set a person's photo

PUT/v1/admin/tenant/users/:id/picture

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/users/:id/picture
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	number

Request body JSON

Name	Type	Description
`image`	any	The image as a data URL (`data:image/png;base64,…`).

Response 200

Field	Type	Description
`profile_picture`	any

Example response

JSON

{
  "profile_picture": null
}

Errors

Status	Message
404	User not found

Example request

Bash

curl -X PUT 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/users/12.5/picture' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image":"…"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/users/12.5/picture', {
  method: 'PUT',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"image":"…"}),
});
const data = await res.json();

Python

import os, requests

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

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"image":"…"}'
Invoke-RestMethod -Method PUT -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/users/12.5/picture' -Headers $headers -ContentType 'application/json' -Body $body

#Remove a person's photo

DELETE/v1/admin/tenant/users/:id/picture

Address: https://<your-org>.brambleit.cloud/api/v1/admin/tenant/users/:id/picture
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	number

Response 200

Field	Type	Description
`profile_picture`	any

Example response

JSON

{
  "profile_picture": null
}

Errors

Status	Message
404	User not found

Example request

Bash

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

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/tenant/users/12.5/picture', {
  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/users/12.5/picture",
    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/users/12.5/picture' -Headers $headers

#Change one field on a person

PATCH/v1/admin/tenant/user

Update a single field on a tenant user. Requires the GLOBAL_ADMIN role. Generic single-field setter — updatedField must be one of first_name, last_name, email, recovery_email, display_name, profile_picture, status; updatedData is the new value.

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

Request body JSON

Name	Type	Description
`user_id`	integer
`updatedField`	string	The field to change.
`updatedData`	number	Its new value.

Response 200

Field	Type	Description
`message`	string

Example response

JSON

{
  "message": "Saved"
}

Errors

Status	Message
400	Invalid updatedField value
404	User not found

Example request

Bash

curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/user' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":7,"updatedField":"string","updatedData":12.5}'

JavaScript

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

Python

import os, requests

r = requests.patch(
    "https://<your-org>.brambleit.cloud/api/v1/admin/tenant/user",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"user_id":7,"updatedField":"string","updatedData":12.5},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"user_id":7,"updatedField":"string","updatedData":12.5}'
Invoke-RestMethod -Method PATCH -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/tenant/user' -Headers $headers -ContentType 'application/json' -Body $body

#Update a person's name details

PATCH/v1/admin/user/profile

Update a user's display/personal name fields. Requires the GLOBAL_ADMIN role. Only display_name, first_name, last_name, recovery_email are updatable here; only fields actually present in the body are written.

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

Request body JSON

Name	Type	Description
`user_id`required	integer
`display_name`	string
`first_name`	string
`last_name`	string
`recovery_email`	string

Response 200

Field	Type	Description
`success`	boolean
`message`	string

Example response

JSON

{
  "success": true,
  "message": "Saved"
}

Errors

Status	Message
400	user_id is required
400	No valid fields to update
404	Admin user not found
404	User not found

Example request

Bash

curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/admin/user/profile' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":7,"display_name":"Example display name","first_name":"Alex","last_name":"Morgan","recovery_email":"alex@example.com"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/user/profile', {
  method: 'PATCH',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"user_id":7,"display_name":"Example display name","first_name":"Alex","last_name":"Morgan","recovery_email":"alex@example.com"}),
});
const data = await res.json();

Python

import os, requests

r = requests.patch(
    "https://<your-org>.brambleit.cloud/api/v1/admin/user/profile",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"user_id":7,"display_name":"Example display name","first_name":"Alex","last_name":"Morgan","recovery_email":"alex@example.com"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"user_id":7,"display_name":"Example display name","first_name":"Alex","last_name":"Morgan","recovery_email":"alex@example.com"}'
Invoke-RestMethod -Method PATCH -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/user/profile' -Headers $headers -ContentType 'application/json' -Body $body

#Update a person's account

PATCH/v1/admin/user/account

Update a user's account fields (email, status, department, job title, location). Requires the GLOBAL_ADMIN role. Only fields actually present in the body are written.

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

Request body JSON

Name	Type	Description
`user_id`required	integer
`status`	string	`1` active, `0` turned off. Turning someone off signs them out and stops their API keys.
`department`	any
`job_title`	string
`location`	any

Response 200

Field	Type	Description
`success`	boolean
`message`	string

Example response

JSON

{
  "success": true,
  "message": "Saved"
}

Errors

Status	Message
400	user_id is required
400	No valid fields to update
404	Admin user not found
404	User not found

Example request

Bash

curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/admin/user/account' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":7,"status":"active","department":"…","job_title":"Example job title","location":"…"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/user/account', {
  method: 'PATCH',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"user_id":7,"status":"active","department":"…","job_title":"Example job title","location":"…"}),
});
const data = await res.json();

Python

import os, requests

r = requests.patch(
    "https://<your-org>.brambleit.cloud/api/v1/admin/user/account",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"user_id":7,"status":"active","department":"…","job_title":"Example job title","location":"…"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"user_id":7,"status":"active","department":"…","job_title":"Example job title","location":"…"}'
Invoke-RestMethod -Method PATCH -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/user/account' -Headers $headers -ContentType 'application/json' -Body $body

#A person's username and aliases

GET/v1/admin/user/addresses

A user's username and aliases. Requires the GLOBAL_ADMIN role. Mail to any of these addresses reaches the user's mailbox; only the username signs in.

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

Query parameters

Name	Type	Description
`user_id`	number

Response 200

Field	Type	Description
`success`	boolean
`username`	string
`aliases`	array of any
`mailbox_domain`	string

Example response

JSON

{
  "success": true,
  "username": "Example username",
  "aliases": [],
  "mailbox_domain": "string"
}

Errors

Status	Message
404	User not found

Example request

Bash

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

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/user/addresses', {
  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/user/addresses",
    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/user/addresses' -Headers $headers

#Change a person's username

PATCH/v1/admin/user/username

Change a user's username. Requires the GLOBAL_ADMIN role. The new address must be on a verified domain and not anyone's username or alias. With keep_old_as_alias (default true) the old username stays as an alias, so mail to it keeps arriving. Sign-in moves to the new username.

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

Request body JSON

Name	Type	Description
`user_id`	number
`local_part`	any
`domain`	string
`keep_old_as_alias`	boolean	Keep the old address as an alias so mail still arrives.

Response 200

Field	Type	Description
`success`	boolean
`message`	string
`username`	string

Example response

JSON

{
  "success": true,
  "message": "Saved",
  "username": "Example username"
}

Errors

Status	Message
404	User not found
409	That address is already someone's username or alias.

Example request

Bash

curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/admin/user/username' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":12.5,"local_part":"…","domain":"string","keep_old_as_alias":false}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/user/username', {
  method: 'PATCH',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"user_id":12.5,"local_part":"…","domain":"string","keep_old_as_alias":false}),
});
const data = await res.json();

Python

import os, requests

r = requests.patch(
    "https://<your-org>.brambleit.cloud/api/v1/admin/user/username",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"user_id":12.5,"local_part":"…","domain":"string","keep_old_as_alias":False},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"user_id":12.5,"local_part":"…","domain":"string","keep_old_as_alias":false}'
Invoke-RestMethod -Method PATCH -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/user/username' -Headers $headers -ContentType 'application/json' -Body $body

#Add an email alias

POST/v1/admin/user/aliases

Add an alias to a user. Requires the GLOBAL_ADMIN role. The alias must be on a verified domain and not anyone's username or alias.

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

Request body JSON

Name	Type	Description
`user_id`	number
`local_part`	any
`domain`	string

Response 201

Field	Type	Description
`success`	boolean
`id`	integer
`email`	string

Example response

JSON

{
  "success": true,
  "id": 42,
  "email": "alex@example.com"
}

Errors

Status	Message
404	User not found
409	That address is already someone's username or alias.

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/admin/user/aliases' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":12.5,"local_part":"…","domain":"string"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/user/aliases', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"user_id":12.5,"local_part":"…","domain":"string"}),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/api/v1/admin/user/aliases",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"user_id":12.5,"local_part":"…","domain":"string"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"user_id":12.5,"local_part":"…","domain":"string"}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/user/aliases' -Headers $headers -ContentType 'application/json' -Body $body

#Remove an email alias

DELETE/v1/admin/user/aliases/:id

Remove an alias from a user. Requires the GLOBAL_ADMIN role. Mail to the address stops arriving.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/user/aliases/: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	number

Query parameters

Name	Type	Description
`user_id`	number

Response 200

Field	Type	Description
`success`	boolean
`email`	string

Example response

JSON

{
  "success": true,
  "email": "alex@example.com"
}

Errors

Status	Message
404	User not found
404	Alias not found

Example request

Bash

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

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/user/aliases/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/user/aliases/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/user/aliases/12.5' -Headers $headers

#Change a person's mailbox

PATCH/v1/admin/user/mailbox

Update a user's mailbox settings. Requires the GLOBAL_ADMIN role. Updates the mailboxes table row for the user (enabled, quota, plan, forwarding address); only fields actually present in the body are written.

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

Request body JSON

Name	Type	Description
`user_id`required	integer
`mailbox_enabled`	any	Whether they have a mailbox.
`mailbox_quota_gb`	any	Mailbox size in GB.
`mailbox_plan`	any	The mailbox plan.
`forwarding_address`	any	Forward their mail to this address, or empty for none.

Response 200

Field	Type	Description
`success`	boolean
`message`	string

Example response

JSON

{
  "success": true,
  "message": "Saved"
}

Errors

Status	Message
400	user_id is required
400	No fields to update
404	Admin user not found
404	Mailbox not found

Example request

Bash

curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/admin/user/mailbox' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":7,"mailbox_enabled":"…","mailbox_quota_gb":"…","mailbox_plan":"…","forwarding_address":"…"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/user/mailbox', {
  method: 'PATCH',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"user_id":7,"mailbox_enabled":"…","mailbox_quota_gb":"…","mailbox_plan":"…","forwarding_address":"…"}),
});
const data = await res.json();

Python

import os, requests

r = requests.patch(
    "https://<your-org>.brambleit.cloud/api/v1/admin/user/mailbox",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"user_id":7,"mailbox_enabled":"…","mailbox_quota_gb":"…","mailbox_plan":"…","forwarding_address":"…"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"user_id":7,"mailbox_enabled":"…","mailbox_quota_gb":"…","mailbox_plan":"…","forwarding_address":"…"}'
Invoke-RestMethod -Method PATCH -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/user/mailbox' -Headers $headers -ContentType 'application/json' -Body $body

#Set a person's groups

PATCH/v1/admin/user/groups

Replaces their group memberships with exactly this list.

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

Request body JSON

Name	Type	Description
`user_id`required	integer
`group_ids`	array of any

Response 200

Field	Type	Description
`success`	boolean
`message`	string

Example response

JSON

{
  "success": true,
  "message": "Saved"
}

Errors

Status	Message
400	user_id and group_ids (array) are required
404	Admin user not found

Example request

Bash

curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/admin/user/groups' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":7,"group_ids":[]}'

JavaScript

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

Python

import os, requests

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

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"user_id":7,"group_ids":[]}'
Invoke-RestMethod -Method PATCH -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/user/groups' -Headers $headers -ContentType 'application/json' -Body $body

#Set a person's roles

PATCH/v1/admin/user/roles

Replaces their roles with exactly this list. You can't remove your own Global Administrator role, or the organisation's last one.

Address: https://<your-org>.brambleit.cloud/api/v1/admin/user/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
`user_id`required	number
`roles`	array of any

Response 200

Field	Type	Description
`success`	boolean
`message`	string
`roles`	array of any

Example response

JSON

{
  "success": true,
  "message": "Saved",
  "roles": []
}

Errors

Status	Message
400	user_id is required
400	roles must be an array
400	One or more roles are invalid
404	Admin 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.
404	User not found

Example request

Bash

curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/admin/user/roles' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":12.5,"roles":[]}'

JavaScript

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

Python

import os, requests

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

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"user_id":12.5,"roles":[]}'
Invoke-RestMethod -Method PATCH -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/user/roles' -Headers $headers -ContentType 'application/json' -Body $body

#Set a person's licences

PATCH/v1/admin/user/licenses

Replaces their licence packages with exactly this list. Fails if a package has no free seats.

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

Request body JSON

Name	Type	Description
`user_id`required	integer
`license_ids`	array of any

Response 200

Field	Type	Description
`success`	boolean
`message`	string

Example response

JSON

{
  "success": true,
  "message": "Saved",
  "…mailWarning ? { mail_war": "…"
}

Errors

Status	Message
400	user_id and license_ids (array) are required
400	One or more selected packages have no seats available
404	Admin user not found

Example request

Bash

curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/admin/user/licenses' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":7,"license_ids":[]}'

JavaScript

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

Python

import os, requests

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

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"user_id":7,"license_ids":[]}'
Invoke-RestMethod -Method PATCH -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/user/licenses' -Headers $headers -ContentType 'application/json' -Body $body

#Reset a person's password

PATCH/v1/admin/user/security

Reset a user's login password. Requires the GLOBAL_ADMIN role. new_password and confirm_password must match. Best-effort syncs the new plaintext password to the user's mailbox too (skipped for guests, who never have a mailbox), using their current mail-license enabled state.

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

Request body JSON

Name	Type	Description
`user_id`required	integer
`new_password`required	any
`confirm_password`required	any

Response 200

Field	Type	Description
`success`	boolean
`message`	string

Example response

JSON

{
  "success": true,
  "message": "Saved"
}

Errors

Status	Message
400	user_id is required
400	Nothing to update – password fields are empty
400	New password and confirmation do not match
404	Admin user not found
404	User not found

Example request

Bash

curl -X PATCH 'https://<your-org>.brambleit.cloud/api/v1/admin/user/security' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":7,"new_password":"…","confirm_password":"…"}'

JavaScript

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

Python

import os, requests

r = requests.patch(
    "https://<your-org>.brambleit.cloud/api/v1/admin/user/security",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"user_id":7,"new_password":"…","confirm_password":"…"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"user_id":7,"new_password":"…","confirm_password":"…"}'
Invoke-RestMethod -Method PATCH -Uri 'https://<your-org>.brambleit.cloud/api/v1/admin/user/security' -Headers $headers -ContentType 'application/json' -Body $body

#Reset a person's two-step sign-in

POST/v1/admin/user/mfa/reset

Turns off their authenticator so they can set it up again at next sign-in.

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

Request body JSON

Name	Type	Description
`user_id`required	integer

Response 200

Field	Type	Description
`success`	boolean
`message`	string

Example response

JSON

{
  "success": true,
  "message": "Saved"
}

Errors

Status	Message
400	user_id is required
404	User not found

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/admin/user/mfa/reset' \
  -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/user/mfa/reset', {
  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/user/mfa/reset",
    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/user/mfa/reset' -Headers $headers -ContentType 'application/json' -Body $body

#Delete a person

DELETE/v1/admin/user

Permanently deletes the account. Their mailbox is either turned into a shared mailbox (shared) or deleted with all its mail (delete). You can't delete yourself.

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

Request body JSON

Name	Type	Description
`user_id`required	number
`mailbox`	string: "shared" \| "delete"

Response 200

Field	Type	Description
`success`	boolean
`message`	string
`mailbox`	any

Example response

JSON

{
  "success": true,
  "message": "Saved",
  "mailbox": null
}

Errors

Status	Message
400	user_id is required
400	You cannot remove your own account
400	mailbox must be 'shared' or 'delete'
404	Admin user not found
404	User not found
503	The mail server isn't answering, so their mailbox can't be dealt with. Nothing was removed; try again in a few minutes.

Example request

Bash

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

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/v1/admin/user', {
  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/user",
    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/user' -Headers $headers

Was this page helpful?