BrambleHelp
How-to guideDevelopers

Authentication

How to sign in to the Bramble API from a browser, a script, or another application.

Updated 14 November 20264 min read

Every request to Bramble is made as a person. It can do exactly what that person could do in the apps (their licences, roles and permissions), no more. There are four ways to prove who you are.

Method Use it for Works with
API key (X-API-Key) Scripts, servers, integrations BRM-API (/api/...), Drive, Sites
Browser session (cookies) Pages running inside Bramble Every app
Bramble app access token (Authorization: Bearer) Bramble's own apps (Bramble Sync, the mobile apps) BRM-API, Drive, Sites
App password (HTTP Basic) Mail, calendar and contacts apps IMAP/SMTP, CalDAV, CardDAV

To let people sign in to your application with their Bramble account, see Single sign-on.

#API keys

An API key lets a script call Bramble as you.

  1. Sign in and open Hub → Account → API keys.
  2. Choose Create API key. The key is shown once. Copy it into your password manager or your script's secret store.
  3. Send it on every request in the X-API-Key header:
Bash
curl -H "X-API-Key: $BRAMBLE_KEY" \
  https://<your-org>.brambleit.cloud/api/v1/tenant/info

Things to know:

  • Keys last 30 days. Create a new one before the old one expires.
  • A key is you. It has your licences and permissions. For an integration that should outlive one person, create a dedicated user for it and give that user only the licences and roles it needs.
  • Revoke a key on the same page. It stops working immediately.
  • A key stops working with its owner. When the account is turned off (someone leaves, or an admin suspends them), every key they made stops too.
  • Keys are stored hashed. Bramble can't show you a key again, only revoke it.
  • A key can't act for another organisation. Partner delegated admin only works from a signed-in browser.

#Browser sessions

When someone signs in, BRM-Auth sets two cookies on .brambleit.cloud:

  • sso_session: a short-lived (10 minute) signed token.
  • session_id: the long-lived session. Your organisation's session policy sets how long it lasts, from 1 to 90 days (default 7).

Apps renew sso_session from session_id automatically. Pages served by Bramble can call any app's API with fetch(url, { credentials: 'include' }). Other websites can't: browsers only allow Bramble's own addresses to make signed-in requests.

Signing out (POST /auth/logout) ends the session; POST /auth/logout-all ends every session the person has.

#Access tokens for Bramble apps

Bramble's own apps (Bramble Sync on the desktop, the mobile apps) sign in with OpenID Connect and send an access token:

HTTP
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Only access tokens issued to Bramble's own apps are accepted by the API. Tokens given to other applications through "Sign in with Bramble" (for example a Git server or a wiki you connected) only prove who someone is to that application. They can't be used to call Bramble.

#App passwords (Mail, Calendar, Contacts)

Mail clients, phones and calendar apps can't do Bramble's two-step sign-in, so they use an app password: Hub → Account → App passwords. Use your email address as the username.

  • IMAP and SMTP: your mail server settings from Bramble Mail.
  • CalDAV and CardDAV: https://<your-org>.brambleit.cloud/mail/dav/ (most apps find it from just https://<your-org>.brambleit.cloud).

#Single sign-on for your own apps (OpenID Connect)

Bramble is an OpenID Connect provider. An admin registers your application in Admin Centre → Single Sign-On and gets a client ID (and secret for server apps). Discovery:

https://<your-org>.brambleit.cloud/.well-known/openid-configuration
Endpoint Address
Authorise /auth/oidc/authorize
Token /auth/oidc/token
User info /auth/oidc/userinfo
Keys (JWKS) /auth/oidc/jwks.json
Device authorisation /auth/oidc/device_authorization
  • Flows: authorisation code (with PKCE, S256), refresh token, and device code for apps without a browser.
  • Scopes: openid, profile, email, groups (the person's Bramble groups; the claim name can be changed per app).
  • Tokens are RS256-signed. Check them against the JWKS, and check iss is your organisation's address and aud is your client ID.
  • Who may use the app (everyone, or chosen groups) is set when it's registered. People see a consent screen the first time.

#Service credentials

Some routes in the reference are for Bramble's own services talking to each other, and are marked so. They use keys that never leave the platform (X-Flows-Key, X-Drive-Internal-Key, X-Warden-Internal-Key, X-Blob-Key, the RMM agent's device certificate). You can't use them from outside, and you don't need to.

#Sign-in protection

  • Ten wrong passwords or two-step codes for one account within 15 minutes pause sign-in for that account for 15 minutes.
  • Organisations can require two-step sign-in and block sign-in by location with security policies (conditional access) in the Admin Centre.
  • Every sign-in, success or failure, is recorded in the Admin Centre's sign-in activity, and changes in the audit log.