Skip to main content
PUT
/
v1
/
b2b
/
sso
/
saml
/
{organization_id}
/
connections
/
{connection_id}
C#
// PUT /v1/b2b/sso/saml/{organization_id}/connections/{connection_id}
const stytch = require('stytch');

const client = new stytch.B2BClient({
  project_id: '${projectId}',
  secret: '${secret}',
});

const params = {
  organization_id: "${organizationId}",
  connection_id: "${samlConnectionId}",
  x509_certificate: "${exampleCertificate}",
  idp_sso_url: "${exampleIdpSsoUrl}",
  signing_private_key: "${examplePrivateKey}",
  saml_encryption_private_key: "${examplePrivateKey}",
};

const options = {
  authorization: {
    session_token: '${sessionToken}',
  },
};

client.SSO.SAML.UpdateConnection(params, options)
  .then(resp => { console.log(resp) })
  .catch(err => { console.log(err) });
{
  "request_id": "<string>",
  "status_code": 123,
  "connection": {
    "organization_id": "<string>",
    "connection_id": "<string>",
    "status": "<string>",
    "idp_entity_id": "<string>",
    "display_name": "<string>",
    "idp_sso_url": "<string>",
    "acs_url": "<string>",
    "audience_uri": "<string>",
    "signing_certificates": [
      {
        "certificate_id": "<string>",
        "certificate": "<string>",
        "issuer": "<string>",
        "created_at": "<string>",
        "expires_at": "<string>",
        "updated_at": "<string>"
      }
    ],
    "verification_certificates": [
      {
        "certificate_id": "<string>",
        "certificate": "<string>",
        "issuer": "<string>",
        "created_at": "<string>",
        "expires_at": "<string>",
        "updated_at": "<string>"
      }
    ],
    "encryption_private_keys": [
      {
        "private_key_id": "<string>",
        "private_key": "<string>",
        "created_at": "<string>"
      }
    ],
    "saml_connection_implicit_role_assignments": [
      {
        "role_id": "<string>"
      }
    ],
    "saml_group_implicit_role_assignments": [
      {
        "role_id": "<string>",
        "group": "<string>"
      }
    ],
    "alternative_audience_uri": "<string>",
    "identity_provider": "<string>",
    "nameid_format": "<string>",
    "alternative_acs_url": "<string>",
    "idp_initiated_auth_disabled": true,
    "allow_gateway_callback": true,
    "attribute_mapping": {}
  }
}
RBAC Enforced APIIf a Member Session is passed in the Authorization headers, Stytch will enforce that the Member has permission to take the Action on the Resource prior to honoring the request.To learn more, see the RBAC guide.
A newly created connection will not become active until all the following are provided:
  • idp_sso_url
  • attribute_mapping
  • idp_identity_id
  • x509_certificates

Authorizations

​
Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Headers

​
X-Stytch-Member-Session
string

A Stytch session that can be used to run the request with the given member's permissions.

​
X-Stytch-Member-SessionJWT
string

A Stytch Session JSON Web Token (JWT) that can be used to run the request with the given member's permissions.

Path Parameters

​
organization_id
string
required

Globally unique UUID that identifies a specific Organization. The organization_id is critical to perform operations on an Organization, so be sure to preserve this value. You may also use the organization_slug or organization_external_id here as a convenience.

​
connection_id
string
required

Globally unique UUID that identifies a specific SSO connection_id for a Member.

Body

application/json

Request type

​
idp_entity_id
string

A globally unique name for the IdP. This will be provided by the IdP.

​
display_name
string

A human-readable display name for the connection.

​
attribute_mapping
object

An object that represents the attributes used to identify a Member. This object will map the IdP-defined User attributes to Stytch-specific values. Required attributes: email and one of full_name or first_name and last_name.

​
x509_certificate
string

A certificate that Stytch will use to verify the sign-in assertion sent by the IdP, in PEM format. See our X509 guide for more info.

​
idp_sso_url
string

The URL for which assertions for login requests will be sent. This will be provided by the IdP.

​
saml_connection_implicit_role_assignments
object[]

All Members who log in with this SAML connection will implicitly receive the specified Roles. See the RBAC guide for more information about role assignment.

​
saml_group_implicit_role_assignments
object[]

Defines the names of the SAML groups that grant specific role assignments. For each group-Role pair, if a Member logs in with this SAML connection and belongs to the specified SAML group, they will be granted the associated Role. See the RBAC guide for more information about role assignment. Before adding any group implicit role assignments, you must add a "groups" key to your SAML connection's attribute_mapping. Make sure that your IdP is configured to correctly send the group information.

​
alternative_audience_uri
string

An alternative URL to use for the Audience Restriction. This value can be used when you wish to migrate an existing SAML integration to Stytch with zero downtime. Read our SSO migration guide for more info.

​
identity_provider
enum<string>

Name of the IdP. Enum with possible values: classlink, cyberark, duo, google-workspace, jumpcloud, keycloak, miniorange, microsoft-entra, okta, onelogin, pingfederate, rippling, salesforce, shibboleth, or generic.

Specifying a known provider allows Stytch to handle any provider-specific logic.

Available options:
classlink,
cyberark,
duo,
generic,
google-workspace,
jumpcloud,
keycloak,
miniorange,
microsoft-entra,
okta,
onelogin,
pingfederate,
rippling,
salesforce,
shibboleth
​
signing_private_key
string

A PKCS1 format RSA private key used for signing SAML requests. Only PKCS1 format (starting with "-----BEGIN RSA PRIVATE KEY-----") is supported. When provided, Stytch will generate a new x509 certificate from this key and return it in the signing_certificates array.

​
nameid_format
string

The NameID format the SAML Connection expects to use. Defaults to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.

​
alternative_acs_url
string

An alternative URL to use for the AssertionConsumerServiceURL in SP initiated SAML AuthNRequests. This value can be used when you wish to migrate an existing SAML integration to Stytch with zero downtime. Note that you will be responsible for proxying requests sent to the Alternative ACS URL to Stytch. Read our SSO migration guide for more info.

​
idp_initiated_auth_disabled
boolean

Determines whether IDP initiated auth is allowed for a given SAML connection. Defaults to false (IDP Initiated Auth is enabled).

​
saml_encryption_private_key
string

A PKCS1 format RSA private key used to decrypt encrypted SAML assertions. Only PKCS1 format (starting with "-----BEGIN RSA PRIVATE KEY-----") is supported.

​
allow_gateway_callback
boolean

Response

Successful response

​
request_id
string
required

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.

​
status_code
integer<int32>
required

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.

​
connection
object