sso

Create a new SSO configuration for an organization

Each organization can have at most one SSO configuration. Creating a config for an organization that already has one will result in a 409 Conflict error.

post/admin/v1/organizations/{org_slug}/sso-config

Request

Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
URL: /admin/v1/organizations/{org_slug}/sso-config
Auth: HTTP bearer

Path parameters

org_slugstring required

Organization slug

Request body

allowed_email_domainsstring[]

Allowed email domains (empty = allow all)

client_idstring nullable

OAuth2 client ID (required for OIDC, not used for SAML)

client_secretstring nullable

OAuth2 client secret (will be stored in secret manager) Required for OIDC, not used for SAML

create_usersboolean

Whether to create new users on first login (default: true)

default_org_rolestring

Default role for new users in the organization (default: "member")

default_team_idstring uuid nullable

Default team to add new users to (optional)

default_team_rolestring

Default role for new users in the default team (default: "member")

discovery_urlstring nullable

Discovery URL for OIDC metadata (optional - defaults to issuer/.well-known/openid-configuration)

enabledboolean

Whether this SSO config is active (default: true)

enforcement_mode'optional' | 'required' | 'test'

SSO enforcement mode.

groups_claimstring nullable

JWT claim containing group memberships (optional)

identity_claimstring

JWT claim to use as the user's identity (default: "sub")

issuerstring nullable

OIDC issuer URL (e.g., "https://accounts.google.com") Required for OIDC, not used for SAML

org_claimstring nullable

JWT claim containing organization IDs (optional)

provider_type'oidc' | 'saml'

SSO provider type.

provisioning_enabledboolean

Whether JIT provisioning is enabled (default: true)

redirect_uristring nullable

Redirect URI for OAuth2 callback (optional - uses global default if not set)

saml_authn_context_class_refstring nullable

Requested authentication context class

saml_email_attributestring nullable

SAML attribute name for email

saml_force_authnboolean

Whether to force re-authentication at IdP (default: false)

saml_groups_attributestring nullable

SAML attribute name for groups

saml_identity_attributestring nullable

SAML attribute name for user identity (like identity_claim for OIDC)

saml_idp_certificatestring nullable

IdP X.509 certificate for signature validation (PEM format)

saml_idp_entity_idstring nullable

IdP entity identifier (e.g., "https://idp.example.com/metadata")

saml_idp_slo_urlstring nullable

IdP Single Logout service URL (optional)

saml_idp_sso_urlstring nullable

IdP Single Sign-On service URL (HTTP-Redirect or HTTP-POST binding)

saml_metadata_urlstring nullable

IdP metadata URL for auto-configuration (alternative to manual config)

saml_name_attributestring nullable

SAML attribute name for display name

saml_name_id_formatstring nullable

NameID format to request (e.g., 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress')

saml_sign_requestsboolean

Whether to sign AuthnRequests (default: false)

saml_sp_certificatestring nullable

SP X.509 certificate for metadata (PEM format)

saml_sp_entity_idstring nullable

Service Provider entity ID (Hadrian's identifier to the IdP)

saml_sp_private_keystring nullable

SP private key for signing AuthnRequests (PEM format, will be stored in secret manager)

scopesstring[]

OAuth2 scopes to request (defaults to ["openid", "email", "profile"])

sync_attributes_on_loginboolean

Whether to sync user attributes on each login (default: false)

sync_memberships_on_loginboolean

Whether to sync team memberships from IdP groups on each login (default: true)

Response

SSO config created

allowed_email_domainsstring[] required

Allowed email domains (empty = allow all)

client_idstring nullable

OAuth2 client ID (required for OIDC, not used for SAML)

create_usersboolean required

Whether to create new users on first login

created_atstring date-time required

When this config was created

default_org_rolestring required

Default role for new users in the organization

default_team_idstring uuid nullable

Default team to add new users to (optional)

default_team_rolestring required

Default role for new users in the default team

discovery_urlstring nullable

Discovery URL for OIDC metadata (defaults to issuer/.well-known/openid-configuration)

enabledboolean required

Whether this SSO config is active

enforcement_mode'optional' | 'required' | 'test' required

SSO enforcement mode.

groups_claimstring nullable

JWT claim containing group memberships (optional, OIDC only)

idstring uuid required

Unique identifier for this SSO configuration

identity_claimstring nullable

JWT claim to use as the user's identity (default: "sub") Required for OIDC, not used for SAML (use saml_identity_attribute instead)

issuerstring nullable

OIDC issuer URL (e.g., "https://accounts.google.com") Required for OIDC, not used for SAML

org_claimstring nullable

JWT claim containing organization IDs (optional, OIDC only)

org_idstring uuid required

Organization this SSO config belongs to (one config per org)

provider_type'oidc' | 'saml' required

SSO provider type.

provisioning_enabledboolean required

Whether JIT provisioning is enabled for this SSO config

redirect_uristring nullable

Redirect URI for OAuth2 callback (optional - uses global default if not set)

saml_authn_context_class_refstring nullable

Requested authentication context class

saml_email_attributestring nullable

SAML attribute name for email

saml_force_authnboolean required

Whether to force re-authentication at IdP

saml_groups_attributestring nullable

SAML attribute name for groups

saml_identity_attributestring nullable

SAML attribute name for user identity (like identity_claim for OIDC)

saml_idp_certificatestring nullable

IdP X.509 certificate for signature validation (PEM format)

saml_idp_entity_idstring nullable

IdP entity identifier (e.g., "https://idp.example.com/metadata")

saml_idp_slo_urlstring nullable

IdP Single Logout service URL (optional)

saml_idp_sso_urlstring nullable

IdP Single Sign-On service URL (HTTP-Redirect or HTTP-POST binding)

saml_metadata_urlstring nullable

IdP metadata URL for auto-configuration (alternative to manual config)

saml_name_attributestring nullable

SAML attribute name for display name

saml_name_id_formatstring nullable

NameID format to request (e.g., 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress')

saml_sign_requestsboolean required

Whether to sign AuthnRequests

saml_sp_certificatestring nullable

SP X.509 certificate for SP metadata (PEM format) Include when request signing is enabled so IdPs can verify signatures

saml_sp_entity_idstring nullable

Service Provider entity ID (Hadrian's identifier to the IdP)

scopesstring[] required

OAuth2 scopes to request (e.g., ["openid", "email", "profile"]) Empty for SAML configs

sync_attributes_on_loginboolean required

Whether to sync user attributes (email, name) on each login

sync_memberships_on_loginboolean required

Whether to sync team memberships from IdP groups on each login

updated_atstring date-time required

When this config was last updated

Changes

No recorded changes to this operation across all 1 revision of this API.