---
title: "Create SSO connection"
method: POST
path: "/v1/sso-connections"
tags: ["sso-connections"]
---

# Create SSO connection

`POST /v1/sso-connections`

## Request

- Base URL: `https://api.brixsignage.com`
- URL: `https://api.brixsignage.com/v1/sso-connections`
- Auth: HTTP bearer

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

- object
  - `displayName` string, required
  - `vendor` string: Free text, e.g. `okta`, `entra`.
  - `issuer` string, required: Must start with `https://`. A trailing slash is removed.
  - `clientId` string, required
  - `clientSecret` string, required: Encrypted before it is stored; never returned.
  - `emailDomains` string, required: Comma-separated email domains, e.g. `acme.com,acme.org`.
  - `jitProvisioning` boolean: Default true.
  - `enabled` boolean: Default true.
  - `defaultRoleId` string, nullable: You must be able to grant this role for the whole workspace.
  - `claimMapping` SsoClaimMapping: Rules that turn identity-provider claims into a role at a location.
    - `locationClaim` string, nullable, required: The claim whose value names a location (matched to a location's name or Location ID).
    - `rules` object[], required
      - `claim` string, required: The identity-provider claim to read, e.g. `groups`.
      - `match` 'equals' | 'contains', required
      - `value` string, required
      - `roleId` string, required: The role to grant when the rule matches.
      - `at` 'location' | 'root' | 'node', required: Where to grant it: the location named by `locationClaim`, the workspace root, or the fixed `nodeId`.
      - `nodeId` string, nullable: The location for an `at: node` rule.
    - `noMatch` 'default' | 'deny', required: When no rule matches: give `defaultRoleId` at the root, or refuse the sign-in.
  - `extraScopes` string, nullable: Space- or comma-separated scope tokens (at most 20). Null or empty clears them.

## Response `201`

Success.

- object
  - `data` SsoConnection, required: An enterprise single sign-on (OpenID Connect) connection.
    - `id` string, required
    - `displayName` string, required
    - `vendor` string, required: Free text; `generic-oidc` when not set.
    - `issuer` string, required: The OpenID Connect issuer URL (`https://`, no trailing slash).
    - `clientId` string, required
    - `clientSecretPreview` '••••••••', required: Always this mask: the client secret is stored encrypted and is never returned.
    - `emailDomains` string, required: Comma-separated, lower-case (a leading `@` and a trailing dot are removed).
    - `domainsVerifiedAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `provenAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `lastSignInAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `jitProvisioning` boolean, required: Create a person on their first sign-in.
    - `defaultRoleId` string, nullable, required: The role a new person gets at the workspace root when no rule applies.
    - `claimMapping` SsoClaimMapping, required: Rules that turn identity-provider claims into a role at a location.
      - `locationClaim` string, nullable, required: The claim whose value names a location (matched to a location's name or Location ID).
      - `rules` object[], required
        - `claim` string, required: The identity-provider claim to read, e.g. `groups`.
        - `match` 'equals' | 'contains', required
        - `value` string, required
        - `roleId` string, required: The role to grant when the rule matches.
        - `at` 'location' | 'root' | 'node', required: Where to grant it: the location named by `locationClaim`, the workspace root, or the fixed `nodeId`.
        - `nodeId` string, nullable: The location for an `at: node` rule.
      - `noMatch` 'default' | 'deny', required: When no rule matches: give `defaultRoleId` at the root, or refuse the sign-in.
    - `extraScopes` string, nullable, required: Scopes requested on top of `openid email profile`, space-separated.
    - `lastClaims` object, nullable, required: The claims of the last sign-in (a person's email, name and groups). Null unless the caller also holds `user.view` for the whole workspace.
    - `lastClaimsAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `enabled` boolean, required
    - `redirectUri` string, required: The redirect URI to register in the identity provider.
    - `createdAt` string, required: ISO-8601 timestamp (UTC).
    - `updatedAt` string, required: ISO-8601 timestamp (UTC).

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `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.
- `404`: No such connection, role or location in this workspace.
- `422`: A required field is missing, `issuer` is not `https://`, an invalid `claimMapping`, or `extraScopes` is not a valid scope list.
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/02fd3665dc7d?raw)