SutraID|Developer Docs
QuickstartAPI ReferenceDashboard

SSO

SSO provider configuration (SAML 2.0 & OIDC), domain discovery, and authentication flows.

POST/api/v1/organizations/:orgId/sso/providersCreate SSO ProviderBearer Token▾

Create a new SSO provider (SAML 2.0 or OIDC) for an organization. Provide the protocol-specific fields that match the chosen protocol.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hx9k2m4p

Request Body

NameTypeRequiredDescription
namestringRequiredDisplay name for the SSO provider (max 100 characters).e.g. Okta Production
typestringRequiredProvider type.e.g. OKTA
OKTAAZURE_ADGOOGLE_WORKSPACEGENERIC_SAMLGENERIC_OIDC
protocolstringRequiredAuthentication protocol.e.g. SAML2
SAML2OIDC
samlEntityIdstringOptionalSAML IdP Entity ID. Required when protocol is SAML2.e.g. http://www.okta.com/exk1abc2defGHIJK
samlSsoUrlstringOptionalSAML IdP Single Sign-On URL. Required when protocol is SAML2.e.g. https://acme.okta.com/app/acme_sutraid/exk1abc/sso/saml
samlCertificatestringOptionalSAML IdP X.509 signing certificate (PEM). Required when protocol is SAML2.e.g. MIIDpDCCAoygAwIBAgIGAX...
samlMetadataUrlstringOptionalOptional URL to fetch SAML IdP metadata automatically.e.g. https://acme.okta.com/app/exk1abc/sso/saml/metadata
oidcIssuerstringOptionalOIDC Issuer URL. Required when protocol is OIDC.e.g. https://acme.okta.com
oidcClientIdstringOptionalOIDC Client ID. Required when protocol is OIDC.e.g. 0oa1abc2defGHIJK3456
oidcClientSecretstringOptionalOIDC Client Secret. Required when protocol is OIDC.e.g. xyzClientSecretValue
oidcAuthUrlstringOptionalOptional OIDC authorization endpoint URL.e.g. https://acme.okta.com/oauth2/v1/authorize
oidcTokenUrlstringOptionalOptional OIDC token endpoint URL.e.g. https://acme.okta.com/oauth2/v1/token
oidcUserinfoUrlstringOptionalOptional OIDC userinfo endpoint URL.e.g. https://acme.okta.com/oauth2/v1/userinfo
oidcScopesstring[]OptionalOptional list of OIDC scopes to request.e.g. ["openid","email","profile"]
attributeMappingRecord<string, string>OptionalOptional mapping of IdP attribute names to SutraID profile fields.e.g. {"email":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"}
enabledbooleanOptionalWhether the provider is active. Defaults to true.e.g. true
autoProvisionbooleanOptionalAutomatically create user accounts on first SSO login.e.g. true
allowedDomainsstring[]OptionalEmail domains that are allowed to use this SSO provider.e.g. ["acme.com","acme.io"]

Response Fields

NameTypeRequiredDescription
idstringOptionalUnique identifier of the SSO provider.e.g. sso_01hx9k2m4p
orgIdstringOptionalOrganization this provider belongs to.e.g. org_01hx9k2m4p
namestringOptionalDisplay name of the provider.e.g. Okta Production
typestringOptionalProvider type enum value.e.g. OKTA
protocolstringOptionalProtocol used (SAML2 or OIDC).e.g. SAML2
enabledbooleanOptionalWhether the provider is active.e.g. true
autoProvisionbooleanOptionalAuto-provisioning enabled.e.g. true
allowedDomainsstring[]OptionalAllowed email domains.e.g. ["acme.com"]
createdAtstringOptionalISO 8601 creation timestamp.e.g. 2024-01-15T10:00:00.000Z
updatedAtstringOptionalISO 8601 last-updated timestamp.e.g. 2024-01-15T10:00:00.000Z

Response Example

{
  "id": "sso_01hx9k2m4p",
  "orgId": "org_01hx9k2m4p",
  "name": "Okta Production",
  "type": "OKTA",
  "protocol": "SAML2",
  "samlEntityId": "http://www.okta.com/exk1abc2defGHIJK",
  "samlSsoUrl": "https://acme.okta.com/app/acme_sutraid/exk1abc/sso/saml",
  "samlMetadataUrl": "https://acme.okta.com/app/exk1abc/sso/saml/metadata",
  "attributeMapping": {
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  },
  "enabled": true,
  "autoProvision": true,
  "allowedDomains": [
    "acme.com"
  ],
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:00:00.000Z"
}

Code Examples

curl -X POST https://api.sutraid.com/api/v1/organizations/org_01hx9k2m4p/sso/providers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Okta Production",
    "type": "OKTA",
    "protocol": "SAML2",
    "samlEntityId": "http://www.okta.com/exk1abc2defGHIJK",
    "samlSsoUrl": "https://acme.okta.com/app/acme_sutraid/exk1abc/sso/saml",
    "samlCertificate": "MIIDpDCCAoygAwIBAgIGAX...",
    "autoProvision": true,
    "allowedDomains": ["acme.com"]
  }'
GET/api/v1/organizations/:orgId/sso/providersList SSO ProvidersBearer Token▾

Retrieve all SSO providers configured for an organization.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hx9k2m4p

Response Fields

NameTypeRequiredDescription
[]SsoProvider[]OptionalArray of SSO provider records.
[].idstringOptionalUnique provider identifier.e.g. sso_01hx9k2m4p
[].namestringOptionalProvider display name.e.g. Okta Production
[].typestringOptionalProvider type.e.g. OKTA
[].protocolstringOptionalAuthentication protocol.e.g. SAML2
[].enabledbooleanOptionalWhether the provider is active.e.g. true

Response Example

{
  "data": [
    {
      "id": "sso_01hx9k2m4p",
      "orgId": "org_01hx9k2m4p",
      "name": "Okta Production",
      "type": "OKTA",
      "protocol": "SAML2",
      "enabled": true,
      "autoProvision": true,
      "allowedDomains": [
        "acme.com"
      ],
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:00:00.000Z"
    },
    {
      "id": "sso_02hy0l3n5q",
      "orgId": "org_01hx9k2m4p",
      "name": "Azure AD",
      "type": "AZURE_AD",
      "protocol": "OIDC",
      "enabled": true,
      "autoProvision": false,
      "allowedDomains": [
        "acme.io"
      ],
      "createdAt": "2024-02-01T08:30:00.000Z",
      "updatedAt": "2024-02-01T08:30:00.000Z"
    }
  ]
}

Code Examples

curl -X GET https://api.sutraid.com/api/v1/organizations/org_01hx9k2m4p/sso/providers \
  -H "Authorization: Bearer <token>"
GET/api/v1/organizations/:orgId/sso/providers/:providerIdGet SSO ProviderBearer Token▾

Retrieve a single SSO provider by ID.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hx9k2m4p
providerIdstringRequiredThe unique identifier of the SSO provider.e.g. sso_01hx9k2m4p

Response Fields

NameTypeRequiredDescription
idstringOptionalUnique provider identifier.e.g. sso_01hx9k2m4p
orgIdstringOptionalOwning organization ID.e.g. org_01hx9k2m4p
namestringOptionalProvider display name.e.g. Okta Production
typestringOptionalProvider type.e.g. OKTA
protocolstringOptionalAuthentication protocol.e.g. SAML2
enabledbooleanOptionalWhether the provider is active.e.g. true
autoProvisionbooleanOptionalAuto-provisioning enabled.e.g. true
allowedDomainsstring[]OptionalAllowed email domains.e.g. ["acme.com"]
createdAtstringOptionalISO 8601 creation timestamp.e.g. 2024-01-15T10:00:00.000Z
updatedAtstringOptionalISO 8601 last-updated timestamp.e.g. 2024-01-15T10:00:00.000Z

Response Example

{
  "id": "sso_01hx9k2m4p",
  "orgId": "org_01hx9k2m4p",
  "name": "Okta Production",
  "type": "OKTA",
  "protocol": "SAML2",
  "samlEntityId": "http://www.okta.com/exk1abc2defGHIJK",
  "samlSsoUrl": "https://acme.okta.com/app/acme_sutraid/exk1abc/sso/saml",
  "samlMetadataUrl": "https://acme.okta.com/app/exk1abc/sso/saml/metadata",
  "attributeMapping": {
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
  },
  "enabled": true,
  "autoProvision": true,
  "allowedDomains": [
    "acme.com"
  ],
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:00:00.000Z"
}

Code Examples

curl -X GET https://api.sutraid.com/api/v1/organizations/org_01hx9k2m4p/sso/providers/sso_01hx9k2m4p \
  -H "Authorization: Bearer <token>"
PUT/api/v1/organizations/:orgId/sso/providers/:providerIdUpdate SSO ProviderBearer Token▾

Update an existing SSO provider. All fields from CreateSsoProviderDto are accepted; only provided fields are updated.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hx9k2m4p
providerIdstringRequiredThe unique identifier of the SSO provider.e.g. sso_01hx9k2m4p

Request Body

NameTypeRequiredDescription
namestringOptionalNew display name (max 100 characters).e.g. Okta Production v2
samlCertificatestringOptionalUpdated SAML IdP X.509 certificate (PEM).e.g. MIIDpDCCAoygAwIBAgIGAY...
enabledbooleanOptionalEnable or disable the provider.e.g. false
autoProvisionbooleanOptionalToggle auto-provisioning of new users.e.g. true
allowedDomainsstring[]OptionalReplacement list of allowed email domains.e.g. ["acme.com","acme.io"]
attributeMappingRecord<string, string>OptionalUpdated attribute mapping.e.g. {"email":"mail","firstName":"givenName"}

Response Fields

NameTypeRequiredDescription
idstringOptionalUnique provider identifier.e.g. sso_01hx9k2m4p
namestringOptionalUpdated display name.e.g. Okta Production v2
enabledbooleanOptionalUpdated enabled state.e.g. false
updatedAtstringOptionalISO 8601 last-updated timestamp.e.g. 2024-03-10T12:00:00.000Z

Response Example

{
  "id": "sso_01hx9k2m4p",
  "orgId": "org_01hx9k2m4p",
  "name": "Okta Production v2",
  "type": "OKTA",
  "protocol": "SAML2",
  "samlEntityId": "http://www.okta.com/exk1abc2defGHIJK",
  "samlSsoUrl": "https://acme.okta.com/app/acme_sutraid/exk1abc/sso/saml",
  "enabled": false,
  "autoProvision": true,
  "allowedDomains": [
    "acme.com",
    "acme.io"
  ],
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-03-10T12:00:00.000Z"
}

Code Examples

curl -X PUT https://api.sutraid.com/api/v1/organizations/org_01hx9k2m4p/sso/providers/sso_01hx9k2m4p \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Okta Production v2",
    "enabled": false,
    "allowedDomains": ["acme.com", "acme.io"]
  }'
DELETE/api/v1/organizations/:orgId/sso/providers/:providerIdDelete SSO ProviderBearer Token▾

Permanently delete an SSO provider from an organization.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hx9k2m4p
providerIdstringRequiredThe unique identifier of the SSO provider to delete.e.g. sso_01hx9k2m4p

Response Fields

NameTypeRequiredDescription
successbooleanOptionalIndicates whether deletion was successful.e.g. true
messagestringOptionalHuman-readable result message.e.g. SSO provider deleted successfully.

Response Example

{
  "success": true,
  "message": "SSO provider deleted successfully."
}

Code Examples

curl -X DELETE https://api.sutraid.com/api/v1/organizations/org_01hx9k2m4p/sso/providers/sso_01hx9k2m4p \
  -H "Authorization: Bearer <token>"
POST/api/v1/organizations/:orgId/sso/providers/:providerId/testTest SSO ConnectionBearer Token▾

Validate the connectivity and configuration of an SSO provider without initiating an actual login flow.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hx9k2m4p
providerIdstringRequiredThe unique identifier of the SSO provider to test.e.g. sso_01hx9k2m4p

Response Fields

NameTypeRequiredDescription
successbooleanOptionalWhether the connection test passed.e.g. true
messagestringOptionalDescriptive result or error message.e.g. Connection successful. IdP metadata is reachable.

Response Example

{
  "success": true,
  "message": "Connection successful. IdP metadata is reachable."
}

Code Examples

curl -X POST https://api.sutraid.com/api/v1/organizations/org_01hx9k2m4p/sso/providers/sso_01hx9k2m4p/test \
  -H "Authorization: Bearer <token>"
GET/api/v1/sso/discoverDiscover SSO Providers▾

Discover which SSO providers are available for a given email domain. Used on the login page to determine whether to offer SSO options.

Parameters

NameTypeRequiredDescription
domainstringRequiredThe email domain to look up (e.g. acme.com).e.g. acme.com

Response Fields

NameTypeRequiredDescription
providersSsoProvider[]OptionalList of SSO providers matching the domain.
providers[].idstringOptionalProvider identifier.e.g. sso_01hx9k2m4p
providers[].namestringOptionalProvider display name.e.g. Okta Production
providers[].typestringOptionalProvider type.e.g. OKTA
providers[].protocolstringOptionalAuthentication protocol.e.g. SAML2
providers[].orgIdstringOptionalOrganization that owns this provider.e.g. org_01hx9k2m4p

Response Example

{
  "providers": [
    {
      "id": "sso_01hx9k2m4p",
      "orgId": "org_01hx9k2m4p",
      "name": "Okta Production",
      "type": "OKTA",
      "protocol": "SAML2"
    }
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/sso/discover?domain=acme.com"
GET/api/v1/sso/saml/:orgId/loginInitiate SAML Login▾

Begin a SAML 2.0 SP-initiated login flow. The server constructs a SAML AuthnRequest and returns an HTTP 302 redirect to the IdP SSO URL.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe organization whose SAML provider will handle login.e.g. org_01hx9k2m4p
providerIdstringRequiredThe SSO provider ID to use for this login attempt.e.g. sso_01hx9k2m4p

Response Fields

NameTypeRequiredDescription
(HTTP 302)redirectOptionalRedirects the browser to the SAML IdP SSO URL with an embedded AuthnRequest.
LocationstringOptionalHeader containing the IdP redirect target.e.g. https://acme.okta.com/app/acme_sutraid/exk1abc/sso/saml?SAMLRequest=...

Response Example

{
  "status": 302,
  "headers": {
    "Location": "https://acme.okta.com/app/acme_sutraid/exk1abc/sso/saml?SAMLRequest=PHNhbWxwOk..."
  }
}

Code Examples

# Open in a browser or follow redirects with -L
curl -L "https://api.sutraid.com/api/v1/sso/saml/org_01hx9k2m4p/login?providerId=sso_01hx9k2m4p"
POST/api/v1/sso/saml/:orgId/acsSAML Assertion Consumer Service (ACS)▾

Receives the SAML response posted by the IdP after the user authenticates. The server validates the assertion, provisions or resolves the user, issues a JWT, and redirects to the frontend callback URL.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe organization that owns the SAML provider.e.g. org_01hx9k2m4p

Request Body

NameTypeRequiredDescription
SAMLResponsestringRequiredBase64-encoded SAML response document posted by the IdP.e.g. PHNhbWxwOlJlc3BvbnNlIHhtbG5z...
RelayStatestringOptionalOptional opaque value that was included in the original AuthnRequest; echoed back by the IdP.e.g. eyJyZWRpcmVjdCI6Ii9kYXNoYm9hcmQifQ==

Response Fields

NameTypeRequiredDescription
(HTTP 302)redirectOptionalRedirects to the frontend callback URL with an access token in the query string.
LocationstringOptionalFrontend callback URL containing the issued JWT.e.g. https://app.sutraid.com/auth/sso/callback?token=eyJhbGc...

Response Example

{
  "status": 302,
  "headers": {
    "Location": "https://app.sutraid.com/auth/sso/callback?token=eyJhbGciOiJSUzI1NiJ9..."
  }
}

Code Examples

# This endpoint is called by the IdP browser POST, not directly by the client.
# Simulating with curl for testing only:
curl -X POST https://api.sutraid.com/api/v1/sso/saml/org_01hx9k2m4p/acs \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "SAMLResponse=PHNhbWxwOlJlc3BvbnNlIHhtbG5z..." \
  --data-urlencode "RelayState=eyJyZWRpcmVjdCI6Ii9kYXNoYm9hcmQifQ=="
GET/api/v1/sso/saml/:orgId/metadataGet SAML SP Metadata▾

Returns the SAML Service Provider (SP) metadata XML for the given organization. Provide this URL or its content to your IdP during configuration.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe organization whose SP metadata should be returned.e.g. org_01hx9k2m4p

Response Fields

NameTypeRequiredDescription
(XML document)stringOptionalSAML 2.0 EntityDescriptor XML. Content-Type: application/xml.

Response Example

{
  "contentType": "application/xml",
  "body": "<?xml version=\"1.0\"?><EntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" entityID=\"https://api.sutraid.com/api/v1/sso/saml/org_01hx9k2m4p/metadata\">...</EntityDescriptor>"
}

Code Examples

curl -X GET https://api.sutraid.com/api/v1/sso/saml/org_01hx9k2m4p/metadata
GET/api/v1/sso/oidc/:providerId/loginInitiate OIDC Login▾

Begin an OIDC authorization code flow with PKCE. The server generates a code verifier/challenge pair, stores state, and returns an HTTP 302 redirect to the OIDC authorization endpoint.

Parameters

NameTypeRequiredDescription
providerIdstringRequiredThe unique identifier of the OIDC SSO provider.e.g. sso_02hy0l3n5q

Response Fields

NameTypeRequiredDescription
(HTTP 302)redirectOptionalRedirects the browser to the OIDC authorization URL with PKCE parameters.
LocationstringOptionalAuthorization endpoint URL with query parameters.e.g. https://acme.okta.com/oauth2/v1/authorize?client_id=...&code_challenge=...&state=...

Response Example

{
  "status": 302,
  "headers": {
    "Location": "https://acme.okta.com/oauth2/v1/authorize?response_type=code&client_id=0oa1abc&scope=openid+email+profile&redirect_uri=https%3A%2F%2Fapi.sutraid.com%2Fapi%2Fv1%2Fsso%2Foidc%2Fsso_02hy0l3n5q%2Fcallback&state=abc123&code_challenge=xyzPKCE&code_challenge_method=S256"
  }
}

Code Examples

# Open in a browser or follow redirects with -L
curl -L "https://api.sutraid.com/api/v1/sso/oidc/sso_02hy0l3n5q/login"
GET/api/v1/sso/oidc/:providerId/callbackOIDC Callback▾

Handles the authorization code callback from the OIDC provider. The server exchanges the code for tokens using PKCE, retrieves the user profile, provisions or resolves the user, issues a JWT, and redirects to the frontend callback URL.

Parameters

NameTypeRequiredDescription
providerIdstringRequiredThe unique identifier of the OIDC SSO provider.e.g. sso_02hy0l3n5q
codestringRequiredAuthorization code returned by the OIDC provider.e.g. SplxlOBeZQQYbYS6WxSbIA
statestringRequiredOpaque state value that must match the value from the login request.e.g. abc123xyz

Response Fields

NameTypeRequiredDescription
(HTTP 302)redirectOptionalRedirects to the frontend callback URL with an access token.
LocationstringOptionalFrontend callback URL containing the issued JWT.e.g. https://app.sutraid.com/auth/sso/callback?token=eyJhbGc...

Response Example

{
  "status": 302,
  "headers": {
    "Location": "https://app.sutraid.com/auth/sso/callback?token=eyJhbGciOiJSUzI1NiJ9..."
  }
}

Code Examples

# The OIDC provider redirects the user's browser here automatically.
# Simulating the callback with curl (follow redirects to see final destination):
curl -L "https://api.sutraid.com/api/v1/sso/oidc/sso_02hy0l3n5q/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=abc123xyz"