ReferenceHub & account API

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

#OpenID Connect discovery

GET/.well-known/openid-configuration

Address: https://<your-org>.brambleit.cloud/.well-known/openid-configuration
Requires: None: public, or protected by a token in the address or body.

Response 200

Field	Type	Description
`issuer`	any
`authorization_endpoint`	string
`token_endpoint`	string
`userinfo_endpoint`	string
`jwks_uri`	string
`scopes_supported`	array of any
`response_types_supported`	array of string
`device_authorization_endpoint`	string
`grant_types_supported`	array of string
`subject_types_supported`	array of string
`id_token_signing_alg_values_supported`	array of string
`token_endpoint_auth_methods_supported`	array of string
`code_challenge_methods_supported`	array of string
`claims_supported`	array of string

Example response

JSON

{
  "issuer": null,
  "authorization_endpoint": "string",
  "token_endpoint": "…",
  "userinfo_endpoint": "string",
  "jwks_uri": "string",
  "scopes_supported": [],
  "response_types_supported": [
    "string"
  ],
  "device_authorization_endpoint": "string",
  "grant_types_supported": [
    "string"
  ],
  "subject_types_supported": [
    "Example subject types supported"
  ],
  "id_token_signing_alg_values_supported": [
    "…"
  ],
  "token_endpoint_auth_methods_supported": [
    "…"
  ],
  "code_challenge_methods_supported": [
    "string"
  ],
  "claims_supported": [
    "string"
  ]
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/.well-known/openid-configuration', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Signing keys (JWKS)

GET/auth/oidc/jwks.json

Address: https://<your-org>.brambleit.cloud/auth/oidc/jwks.json
Requires: None: public, or protected by a token in the address or body.

Response 200

Field	Type	Description
`keys`	array of any

Example response

JSON

{
  "keys": []
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/auth/oidc/jwks.json', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Start sign-in for an app (authorise)

GET/auth/oidc/authorize

The authorisation endpoint. Send the person here with client_id, redirect_uri, response_type=code, scope, state and (recommended) code_challenge + code_challenge_method=S256. After sign-in and consent, Bramble redirects back with code and state.

Address: https://<your-org>.brambleit.cloud/auth/oidc/authorize
Requires: None: public, or protected by a token in the address or body.

Query parameters

Name	Type	Description
`client_id`required	integer
`redirect_uri`required	any
`response_type`	string
`scope`required	string
`state`	any
`code_challenge`required	any
`code_challenge_method`	string
`nonce`	any

Response

A redirect, a file or page.

Errors

Status	Message
400	This app isn't set up correctly
400	This app isn't registered
400	This app has been disabled
403	Single sign-on is turned off

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/auth/oidc/authorize?client_id=7&redirect_uri=%E2%80%A6&scope=string&code_challenge=%E2%80%A6', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#What the consent screen should show

GET/auth/oidc/consent-info

Address: https://<your-org>.brambleit.cloud/auth/oidc/consent-info
Requires: None: public, or protected by a token in the address or body.

Response 200

Field	Type	Description
`clientName`	string
`scopes`	array of any

Example response

JSON

{
  "clientName": "Example clientname",
  "scopes": []
}

Errors

Status	Message
400	Consent request expired or missing
400	invalid_client
400	Consent request expired or invalid

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/auth/oidc/consent-info', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Allow or deny an app

POST/auth/oidc/consent

Address: https://<your-org>.brambleit.cloud/auth/oidc/consent
Requires: None: public, or protected by a token in the address or body.

Request body JSON

Name	Type	Description
`decision`	string	`allow` or `deny`.

Response

A body, a redirect.

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/auth/oidc/consent', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"decision":"string"}),
});
const data = await res.json();

#Get tokens

POST/auth/oidc/token

The token endpoint (form-encoded). grant_type is authorization_code (with code, redirect_uri, code_verifier), refresh_token (with refresh_token) or urn:ietf:params:oauth:grant-type:device_code (with device_code). Authenticate the app with client_id and client_secret. Returns access_token, id_token, expires_in and, where allowed, refresh_token.

Address: https://<your-org>.brambleit.cloud/auth/oidc/token
Requires: None: public, or protected by a token in the address or body.

Request body JSON

Name	Type	Description
`grant_type`	string

Errors

Status	Message
400	invalid_client
401	invalid_client
403	access_denied
400	unsupported_grant_type

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/auth/oidc/token', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"grant_type":"string"}),
});
const data = await res.json();

#Start device sign-in

POST/auth/oidc/device_authorization

For apps without a browser. Returns a user_code to show and a verification_uri where the person enters it; then poll the token endpoint with the device_code.

Address: https://<your-org>.brambleit.cloud/auth/oidc/device_authorization
Requires: None: public, or protected by a token in the address or body.

Request body JSON

Name	Type	Description
`scope`	any
`device_name`	string

Response 200

Field	Type	Description
`device_code`	any
`user_code`	any
`verification_uri`	any
`verification_uri_complete`	string
`expires_in`	number
`interval`	array of any

Example response

JSON

{
  "device_code": null,
  "user_code": null,
  "verification_uri": null,
  "verification_uri_complete": "string",
  "expires_in": 12.5,
  "interval": []
}

Errors

Status	Message
400	unauthorized_client
400	invalid_client
400	invalid_scope
401	invalid_client

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/auth/oidc/device_authorization', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"scope":"…","device_name":"Example device name"}),
});
const data = await res.json();

#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

Under /oidc/ because BRM-Gateway proxies /oidc/* (and /auth/oidc/* on a tenant domain) on every host; a root /device isn't routed. Signed-out visitors go to /auth/, which is the login page on every gateway host.

Address: https://<your-org>.brambleit.cloud/auth/oidc/device
Requires: None: public, or protected by a token in the address or body.

Response

A redirect, a file or page.

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/auth/oidc/device', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#What a device code is for

GET/auth/oidc/device/info

Address: https://<your-org>.brambleit.cloud/auth/oidc/device/info
Requires: None: public, or protected by a token in the address or body.

Query parameters

Name	Type	Description
`user_code`	any

Response 200

Field	Type	Description
`clientName`	string
`deviceName`	string
`requestedIp`	any
`requestedAt`	string (date-time)
`scopes`	array of any
`user`	object
`user.name`	string
`user.email`	string

Example response

JSON

{
  "clientName": "Example clientname",
  "deviceName": "Example devicename",
  "requestedIp": null,
  "requestedAt": "2026-11-12T09:30:00.000Z",
  "scopes": [],
  "user": {
    "name": "Example name",
    "email": "alex@example.com"
  }
}

Errors

Status	Message
401	Sign in first.
404	That code isn't valid or has expired. Check the code on the device, or start again there.
403	Your account isn't allowed to use …. Ask your administrator.

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/auth/oidc/device/info', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Approve or deny a device

POST/auth/oidc/device/decision

Address: https://<your-org>.brambleit.cloud/auth/oidc/device/decision
Requires: None: public, or protected by a token in the address or body.

Request body JSON

Name	Type	Description
`user_code`	any
`decision`	string

Response 200

Field	Type	Description
`approved`	any

Example response

JSON

{
  "approved": null
}

Errors

Status	Message
415	Unsupported request
401	Sign in first.
404	That code isn't valid or has expired.
403	Your account isn't allowed to use ….
409	This request was already answered.

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/auth/oidc/device/decision', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"user_code":"…","decision":"string"}),
});
const data = await res.json();

#The signed-in person's claims

GET/auth/oidc/userinfo

With the access token as Authorization: Bearer. Returns sub plus profile, email and groups claims for the scopes granted.

Address: https://<your-org>.brambleit.cloud/auth/oidc/userinfo
Requires: None: public, or protected by a token in the address or body.
Headers: authorization

Response 200

Errors

Status	Message
401	invalid_token

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/auth/oidc/userinfo', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

Was this page helpful?