SSO & SCIM

Enterprise single sign-on with OIDC and SAML 2.0, plus SCIM 2.0 for automated user provisioning and deprovisioning from identity providers.

SSO Configuration

The organization is taken from the authenticated session; it is not passed in the request body. Provider-specific settings (issuer, client ID, certificate, etc.) are supplied under provider_config.

List SSO Configs

GET /v1/sso/configs

Query Parameters

Create SSO Config

POST /v1/sso/configs

Request Body (OIDC)

{
  "auth_method": "oidc",
  "provider_config": {
    "issuer": "https://your-org.okta.com",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  },
  "is_active": true,
  "is_default": false
}

Request Body (SAML 2.0)

{
  "auth_method": "saml",
  "provider_config": {
    "entity_id": "https://login.microsoftonline.com/...",
    "sso_url": "https://login.microsoftonline.com/.../saml2",
    "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "is_active": true,
  "is_default": false
}

The organization is taken from the authenticated session. System-assigned fields (id, created_at, updated_at) are never supplied in the request body; they are assigned by the platform. provider_config must not contain plaintext secrets; use encrypted reference fields (for example client_secret_ref) instead.

Response

Returns the full created configuration on success; secret reference values in provider_config are redacted in the response.

{
  "success": true,
  "data": {
    "id": "...",
    "org_id": "...",
    "auth_method": "oidc",
    "provider_config": {
      "issuer": "https://your-org.okta.com",
      "client_id": "your-client-id"
    },
    "is_active": true,
    "is_default": false,
    "created_at": "2026-04-13T10:00:00Z",
    "updated_at": "2026-04-13T10:00:00Z"
  }
}

Response Codes

Update SSO Config

PUT /v1/sso/configs/:id

Delete SSO Config

DELETE /v1/sso/configs/:id

Deleting SSO configuration disables SSO for the organization. Members will fall back to email/password authentication.

OIDC Flow

Authorize

GET /v1/auth/sso/oidc/authorize

Query Parameters

Redirects the user to the configured OIDC provider for authentication. The redirect_uri is validated against the application base URL to prevent open redirects.

Callback

GET /v1/auth/sso/oidc/callback

OIDC provider callback. Exchanges the authorization code for tokens and creates a Backbuild session. This endpoint is called by the identity provider and should not be called directly.

Token Exchange

POST /v1/auth/sso/token-exchange

Exchanges the one-time code produced by the SSO callback for Backbuild access and refresh tokens. This endpoint takes no request body: the exchange code is delivered to the browser in an HttpOnly cookie set by the OIDC callback or SAML ACS handler (this prevents code leakage via browser history, the Referer header, analytics, or logs). The request must include an Origin header that exactly matches the application origin (CSRF protection).

SAML 2.0 Flow

Initiate Login

GET /v1/auth/sso/saml/login

Query Parameters

Generates a SAML AuthnRequest and redirects the user to the identity provider’s SSO URL.

Assertion Consumer Service (ACS)

POST /v1/auth/sso/saml/acs

Receives the SAML Response from the identity provider. Validates the assertion signature, extracts user attributes, and creates a Backbuild session. This endpoint is configured as the ACS URL in your IdP.

Metadata

GET /v1/auth/sso/saml/metadata/:configId

Returns the SAML Service Provider metadata XML for the given SSO configuration. Provide this URL to your identity provider during setup.

SCIM 2.0 Provisioning

SCIM endpoints use per-organization bearer tokens (not user JWTs). Generate a SCIM token from the organization’s SSO settings page and configure it in your identity provider.

List Users

GET /v1/scim/v2/Users

Headers

Authorization: Bearer SCIM_ORG_TOKEN

Query Parameters

Response

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 3,
  "startIndex": 1,
  "itemsPerPage": 20,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "...",
      "userName": "jane@example.com",
      "name": {
        "givenName": "Jane",
        "familyName": "Smith"
      },
      "emails": [
        {
          "value": "jane@example.com",
          "primary": true
        }
      ],
      "active": true
    }
  ]
}

Create User

POST /v1/scim/v2/Users

Request Body

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "newuser@example.com",
  "name": {
    "givenName": "New",
    "familyName": "User"
  },
  "emails": [
    {
      "value": "newuser@example.com",
      "primary": true
    }
  ],
  "active": true
}

Provisions a new user in the organization. If the user already has a Backbuild account, they are added as a member. Otherwise, a new account is created. The organization is resolved from the SCIM bearer token. This endpoint follows the SCIM 2.0 protocol (RFC 7644), so it returns a SCIM User resource (not the standard Backbuild envelope). The resource id is assigned by the platform and is never supplied in the request body.

Response

Returns the full created SCIM User resource, with a Location header pointing at the new resource.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "...",
  "userName": "newuser@example.com",
  "name": {
    "givenName": "New",
    "familyName": "User"
  },
  "emails": [
    { "value": "newuser@example.com", "primary": true }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2026-04-13T10:00:00Z",
    "lastModified": "2026-04-13T10:00:00Z",
    "location": "/v1/scim/v2/Users/..."
  }
}

Response Codes

Errors follow the SCIM error schema (urn:ietf:params:scim:api:messages:2.0:Error) with a scimType where applicable.

Delete User

DELETE /v1/scim/v2/Users/:id

Deprovisions a user from the organization. The user’s Backbuild account is not deleted; only their membership in this organization is removed.