SSO connections API

GET/v1/sso-connections

Returns the workspace's enterprise single sign-on connections, with client secrets masked. The key or person must have settings.view for the whole workspace. A caller limited to a location or to a franchise workspace gets 403. lastClaims holds the claims from the last sign-in: a person's email, name and groups. It is null unless the caller also has user.view for the whole workspace.

curl "https://api.brixsignage.com/v1/sso-connections" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/sso-connections

Creates an enterprise single sign-on connection. The client secret is encrypted before it is stored. **Notes.** - A new connection is unverified: prove its domains (domain-challenge, then verify-domains) before it is offered at sign-in.

Request body application/json

curl -X POST "https://api.brixsignage.com/v1/sso-connections" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"displayName":"Acme Okta","issuer":"https://acme.okta.com","clientId":"0oa1b2c3d4","clientSecret":"example-client-secret","emailDomains":"acme.com"}'

Response 201 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Also: `defaultRoleId` or a rule's role holds permissions you cannot grant there.

Response 404 No such connection, role or location in this workspace.

Response 422 A required field is missing, `issuer` is not `https://`, an invalid `claimMapping`, or `extraScopes` is not a valid scope list.

Response 5XX Server error. The body carries a `requestId` to quote to support.

PATCH/v1/sso-connections/{id}

Updates an enterprise single sign-on connection. clientSecret is optional: when provided, it replaces the stored secret; when omitted, the existing secret is left unchanged. **Notes.** - Changing emailDomains clears domainsVerifiedAt. Changing issuer, clientId, clientSecret or emailDomains clears provenAt.

Request body application/json

curl -X PATCH "https://api.brixsignage.com/v1/sso-connections/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough). Also: `defaultRoleId` or a rule's role holds permissions you cannot grant there.

Response 404 No such connection, role or location in this workspace.

Response 422 A required field is missing, `issuer` is not `https://`, an invalid `claimMapping`, or `extraScopes` is not a valid scope list.

Response 5XX Server error. The body carries a `requestId` to quote to support.

DELETE/v1/sso-connections/{id}

Soft-deletes an enterprise single sign-on connection. **Notes.** - Answers { ok: true }, not the { id, deleted } shape of other deletes. The connection is also disabled.

curl -X DELETE "https://api.brixsignage.com/v1/sso-connections/{id}" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).

Response 404 No such connection in this workspace.

Response 5XX Server error. The body carries a `requestId` to quote to support.

GET/v1/sso-connections/{id}/domain-challenge

Returns the DNS TXT records you must publish to prove control of the email domains used by this SSO connection. The key or person must have settings.view for the whole workspace.

curl "https://api.brixsignage.com/v1/sso-connections/{id}/domain-challenge" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).

Response 404 No such connection in this workspace.

Response 5XX Server error. The body carries a `requestId` to quote to support.

GET/v1/sso-connections/{id}/scim

Returns the SCIM base URL for this SSO connection and a preview of its currently live provisioning tokens. Token secrets themselves are never returned.

curl "https://api.brixsignage.com/v1/sso-connections/{id}/scim" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).

Response 404 No such connection in this workspace.

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/sso-connections/{id}/scim/tokens

Creates a new SCIM provisioning token for this SSO connection. The token value is shown exactly once, in this response. A connection can have at most 5 live tokens at a time. This action cannot be taken while impersonating another user.

curl -X POST "https://api.brixsignage.com/v1/sso-connections/{id}/scim/tokens" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 201 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).

Response 404 No such connection in this workspace.

Response 409 `too_many_tokens`: the connection already has 5 live tokens.

Response 5XX Server error. The body carries a `requestId` to quote to support.

DELETE/v1/sso-connections/{id}/scim/tokens/{tokenId}

Revokes one SCIM provisioning token belonging to this SSO connection.

curl -X DELETE "https://api.brixsignage.com/v1/sso-connections/{id}/scim/tokens/{tokenId}" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).

Response 404 No such connection, or no live token with this id.

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/sso-connections/{id}/test-mapping

Previews the role and location a person would be granted, given a set of example identity-provider claims, by running the same mapping logic used at sign-in. This is read-only and does not sign anyone in or change anything.

Request body application/json

curl -X POST "https://api.brixsignage.com/v1/sso-connections/{id}/test-mapping" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).

Response 404 No such connection in this workspace.

Response 422 `claims` is not an object, or `claimMapping` is invalid.

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/sso-connections/{id}/verify-domains

Verifies an SSO connection's email domains using a DNS TXT record lookup. Verified domains control whether the connection is offered at sign-in and whether cross-workspace sign-in is allowed for that domain. **Notes.** - Answers 200 with verified: false when a domain fails; the connection stays unverified.

curl -X POST "https://api.brixsignage.com/v1/sso-connections/{id}/verify-domains" \
  -H "Authorization: Bearer $BRIX_API_KEY"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 You do not hold the permission for the whole workspace (a grant at one location, or in a franchise workspace, is not enough).

Response 404 No such connection in this workspace.

Response 422 `no_domains`: the connection has no email domains.

Response 5XX Server error. The body carries a `requestId` to quote to support.

POST/v1/sso-connections/test

Fetches the identity provider's OpenID Connect discovery document and returns its parsed authorization, token, and key endpoints, so the connection can be confirmed as reachable before the setup form is submitted. **Notes.** - Needs settings.view held anywhere, unlike the other SSO routes, which need it for the whole workspace.

Request body application/json

curl -X POST "https://api.brixsignage.com/v1/sso-connections/test" \
  -H "Authorization: Bearer $BRIX_API_KEY" \
  -H "Content-Type: application/json"

Response 200 Success.

Response 401 Missing, expired or revoked bearer token.

Response 403 The token lacks the permission this operation needs (see `x-brix-permission`).

Response 422 `issuer` is not `https://`.

Response 502 `discovery_failed` (the provider answered an error), `discovery_incomplete` (an endpoint is missing), or `discovery_threw` (not reachable).

Response 5XX Server error. The body carries a `requestId` to quote to support.