ReferenceHub & account API

Password & two-step sign-in

Change your password; set up two-step sign-in (generate a secret, show it as a QR code, verify a code from the authenticator to switch it on); switch it off.

Method	Path	Summary
GET	`/v1/user/2fa`	Is two-step sign-in on?
POST	`/v1/user/2fa/disable`	Switch off two-step sign-in
POST	`/v1/user/2fa/verify`	Switch on two-step sign-in
POST	`/v1/user/2fa/generate`	Start setting up two-step sign-in
GET	`/user/2fa`	Is two-step sign-in on? (legacy)
POST	`/user/2fa/generate`	Start setting up two-step sign-in (legacy)
POST	`/user/2fa/verify`	Switch on two-step sign-in (legacy)
POST	`/user/2fa/disable`	Switch off two-step sign-in (legacy)
POST	`/user/password/change`	Change your password

#Is two-step sign-in on?

GET/v1/user/2fa

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

Response 200

Field	Type	Description
`totp_enabled`	any

Example response

JSON

{
  "totp_enabled": null,
  "…await mfaRequirement(u)": "…"
}

Errors

Status	Message
404	User not found

Example request

Bash

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

JavaScript

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

#Switch off two-step sign-in

POST/v1/user/2fa/disable

Disable Two-Factor Authentication (2FA) for the authenticated user

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

Response 200

Field	Type	Description
`message`	string

Example response

JSON

{
  "message": "Saved"
}

Errors

Status	Message
404	User not found
403	Your organisation requires two-step sign-in (policy "…"), so it can't be turned off. Ask an administrator if you need help.

Example request

Bash

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

JavaScript

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

#Switch on two-step sign-in

POST/v1/user/2fa/verify

Verify a user's 2FA code and enable 2FA

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

Request body JSON

Name	Type	Description
`verify_code_input`required	any	The 6-digit code from the authenticator app.

Response 200

Field	Type	Description
`message`	string

Example response

JSON

{
  "message": "Saved"
}

Errors

Status	Message
400	Verification code is required
400	Invalid verification code
404	User not found

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/v1/user/2fa/verify' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"verify_code_input":"…"}'

JavaScript

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

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/api/v1/user/2fa/verify",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"verify_code_input":"…"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"verify_code_input":"…"}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/api/v1/user/2fa/verify' -Headers $headers -ContentType 'application/json' -Body $body

#Start setting up two-step sign-in

POST/v1/user/2fa/generate

Returns a new secret and a QR code to scan into an authenticator app. It isn't switched on until a code is verified.

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

Response 200

Field	Type	Description
`twofa`	any

Example response

JSON

{
  "twofa": null
}

Errors

Status	Message
404	User not found

Example request

Bash

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

JavaScript

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

#Is two-step sign-in on? (legacy)

GET/user/2fa

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

Response 200

Field	Type	Description
`result`	any

Example response

JSON

{
  "result": null
}

Errors

Status	Message
404	User not found

Example request

Bash

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

JavaScript

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

#Start setting up two-step sign-in (legacy)

POST/user/2fa/generate

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

Response 200

Field	Type	Description
`twofa`	any

Example response

JSON

{
  "twofa": null
}

Errors

Status	Message
404	User not found

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/user/2fa/generate' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

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

#Switch on two-step sign-in (legacy)

POST/user/2fa/verify

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

Request body JSON

Name	Type	Description
`verify_code_input`	any

Response 200

Field	Type	Description
`message`	string

Example response

JSON

{
  "message": "Saved"
}

Errors

Status	Message
404	User not found
400	Invalid Code

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/user/2fa/verify' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"verify_code_input":"…"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/user/2fa/verify', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"verify_code_input":"…"}),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/api/user/2fa/verify",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"verify_code_input":"…"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"verify_code_input":"…"}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/api/user/2fa/verify' -Headers $headers -ContentType 'application/json' -Body $body

#Switch off two-step sign-in (legacy)

POST/user/2fa/disable

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

Response 200

Field	Type	Description
`message`	string

Example response

JSON

{
  "message": "Saved"
}

Errors

Status	Message
404	User not found

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/user/2fa/disable' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

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

#Change your password

POST/user/password/change

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

Request body JSON

Name	Type	Description
`totp_code`	any	A code from your authenticator, if two-step sign-in is on.
`current_password`	any	Your current password.
`new_password`	any	The new password.

Response 200

Field	Type	Description
`message`	string

Example response

JSON

{
  "message": "Saved"
}

Errors

Status	Message
400	2FA Verified
404	User not found
404	Password update failed
400	Current password incorrect!
400	Invalid TOTP Code!

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/api/user/password/change' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"totp_code":"…","current_password":"…","new_password":"…"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/api/user/password/change', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"totp_code":"…","current_password":"…","new_password":"…"}),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/api/user/password/change",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"totp_code":"…","current_password":"…","new_password":"…"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"totp_code":"…","current_password":"…","new_password":"…"}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/api/user/password/change' -Headers $headers -ContentType 'application/json' -Body $body

Was this page helpful?