ReferenceDevelopers

Hub & account API

The signed-in person's own account (profile, photo, password, two-step sign-in, app passwords, sessions and sign-in history, notifications, pinned apps), their organisation's basics and licences, platform search — and sign-in itself: the session endpoints, API keys and the OpenID Connect provider.

Address: https://<your-org>.brambleit.cloud/api
Sign-in: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Address: https://<your-org>.brambleit.cloud
Sign-in: None for the sign-in endpoints themselves; some need the session_id cookie.
Address: https://<your-org>.brambleit.cloud/hub
Sign-in: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Endpoints: 79
OpenAPI: hub.json
Guides: How Hub & your account works

Two generations of account routes. /v1/user/... and /v1/tenant/... are current. The unversioned /user/... and /tenant/... routes are the originals, kept for older pages; they return the same data. Use /v1.

Sign-in routes (/auth/...) are on your organisation's address too, but are served by BRM-Auth, not BRM-API (no /api prefix). Scripts don't need them: use an API key instead.

Resources

Profile

The signed-in person's own details and photo.

Method	Path	Summary
GET	`/v1/user`	Get your account
GET	`/v1/user/email`	Get your email address
GET	`/v1/user/picture`	Get your photo
PUT	`/v1/user/picture`	Set your photo
DELETE	`/v1/user/picture`	Remove your photo
GET	`/user/info`	Get your account (legacy)
GET	`/user/name`	Get your name (legacy)
GET	`/user/email`	Get your email address (legacy)
GET	`/user/picture`	Get your photo (legacy)

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

Sessions & sign-in history

Where you're signed in (and signing out of those), and your recent sign-ins.

Method	Path	Summary
GET	`/v1/user/login_history`	Your last 15 sign-ins
GET	`/v1/user/login_history/month`	Your sign-ins in the last month
GET	`/v1/user/sessions`	Where you're signed in
POST	`/v1/user/sessions/revoke`	Sign out one session
POST	`/v1/user/sessions/revoke_all`	Sign out everywhere
GET	`/user/login_history`	Your recent sign-ins (legacy)
GET	`/user/login_history/month`	Your sign-ins in the last month (legacy)

App passwords

Passwords for mail, calendar and contacts apps that can't do Bramble's two-step sign-in. Each is shown once when created, and can be revoked on its own.

Method	Path	Summary
GET	`/v1/user/app-passwords`	List your app passwords
POST	`/v1/user/app-passwords`	Create an app password
DELETE	`/v1/user/app-passwords/:id`	Revoke an app password

Notifications

The notification centre (bell) and browser push: list and mark notifications read; register a browser for Web Push.

Method	Path	Summary
GET	`/v1/user/notifications`	List your notifications
POST	`/v1/user/notifications/read`	Mark notifications read
GET	`/v1/user/push/key`	Get the Web Push public key
POST	`/v1/user/push/subscribe`	Register a browser for push notifications
POST	`/v1/user/push/unsubscribe`	Stop push notifications to a browser

Pinned apps

Apps pinned to the launcher rail.

Method	Path	Summary
GET	`/v1/user/faq/:service`	Help articles for an app
GET	`/user/pins`	List your pinned apps
POST	`/user/pins`	Pin an app
DELETE	`/user/pins/:pin_key`	Unpin an app

Your organisation

Read-only views of your organisation for any member: its details, the licences it has, whether it's licensed for an app, its people, groups and domains. (Changing them is in the Admin Centre API.)

Method	Path	Summary
GET	`/v1/tenant/info`	Get your organisation
GET	`/v1/tenant/licenses`	Your organisation's licences
POST	`/v1/tenant/check-license`	Is the organisation licensed for an app?
GET	`/v1/tenant/users`	People in your organisation
GET	`/v1/tenant/groups`	Groups in your organisation
POST	`/v1/tenant/groups/members`	Members of a group
GET	`/v1/tenant/domains`	Your organisation's domains
GET	`/tenant/info`	Get your organisation (legacy)
GET	`/tenant/licenses`	Your organisation's licences (legacy)
POST	`/tenant/check-license`	Is the organisation licensed for an app? (legacy)

Search

Platform search across the apps you're licensed for.

Method	Path	Summary
GET	`/v1/search`	Search

BRM-Auth's sign-in endpoints, used by the sign-in page and by Bramble's own apps. Passwords are sent as the SHA3-512 hex digest of the password (the sign-in page hashes it in the browser; Bramble stores an scrypt hash of that). A successful sign-in sets the sso_session and session_id cookies. Failed attempts are limited to 10 per account per 15 minutes.

Method	Path	Summary
POST	`/auth/mail/verify`	Check a mail sign-in (mail server only)
POST	`/auth/mail/token`	Mail app sign-in (Bramble Mail only)
POST	`/auth/login`	Sign in
POST	`/auth/mfa/setup-generate`	Start required two-step setup during sign-in
POST	`/auth/mfa/setup-verify`	Finish required two-step setup and sign in
POST	`/auth/forgot-password`	Send a password reset email
POST	`/auth/reset-password`	Set a new password from a reset link
POST	`/auth/register/check-slug`	Preview an organisation's address
POST	`/auth/find-workspace`	Find your organisation's address
POST	`/auth/register`	Sign up a new organisation
GET	`/auth/verify-email`	Confirm an email address from a sign-up link
POST	`/auth/refresh`	Renew the short-lived session token
GET	`/auth/validate`	Is this session still valid?
GET	`/auth/bridge`	Carry a sign-in over to the organisation's address
POST	`/auth/logout`	Sign out
POST	`/auth/logout-all`	Sign out everywhere
GET	`/auth/check`	Who is signed in?

API keys

Create, list and revoke your own API keys (the Hub account page uses these). These take the session_id cookie, so you create keys from a signed-in browser; the key itself is then used with X-API-Key everywhere else.

Method	Path	Summary
POST	`/auth/generate-api-key`	Create an API key
GET	`/auth/api-keys`	List your API keys
POST	`/auth/api-keys/:id/revoke`	Revoke an API key

OpenID Connect

Bramble as an OpenID Connect provider ("Sign in with Bramble"): discovery, keys, authorise and consent, token (authorisation code with PKCE, refresh token, device code), device authorisation for apps without a browser, and user info. See single sign-on.

Method	Path	Summary
GET	`/.well-known/openid-configuration`	OpenID Connect discovery
GET	`/auth/oidc/jwks.json`	Signing keys (JWKS)
GET	`/auth/oidc/authorize`	Start sign-in for an app (authorise)
GET	`/auth/oidc/consent-info`	What the consent screen should show
POST	`/auth/oidc/consent`	Allow or deny an app
POST	`/auth/oidc/token`	Get tokens
POST	`/auth/oidc/device_authorization`	Start device sign-in
GET	`/auth/oidc/device`	Under /oidc/ because BRM-Gateway proxies /oidc/* (and /auth/oidc/* on a tenant domain) on every host; a root /device isn't routed
GET	`/auth/oidc/device/info`	What a device code is for
POST	`/auth/oidc/device/decision`	Approve or deny a device
GET	`/auth/oidc/userinfo`	The signed-in person's claims

Web pages

These return pages for the browser rather than data.

GET /auth/forgot
GET /auth/reset-password
GET /auth/signup
GET /auth/provisioning
GET /
GET /403
GET /account
GET /account/2fa
GET /account/password
GET /account/licenses
GET /account/history
GET /apps
GET /assets/js/brm-sw.js