> ## Documentation Index > Fetch the complete documentation index at: https://docs.prelude.so/llms.txt > Use this file to discover all available pages before exploring further. # Update SAML connection > Apply a partial update to a SAML connection. Omitted fields are left unchanged. The IdP `entity_id` is immutable — delete and recreate the connection to rotate it. ## OpenAPI ````yaml put /v2/session/apps/{appID}/config/login/saml/{providerID}/{connectionID} openapi: 3.1.1 info: title: Prelude Session Management API version: 0.0.1 summary: The Prelude API for Session Management description: The Prelude API for Session Management. contact: email: support@prelude.so url: https://prelude.so servers: - url: https://api.prelude.dev description: Production server security: - Authorization: [] tags: - name: Mode description: Manage the mode (dev/prod) of your application. - name: Users description: Manage the users of your application. - name: Webhooks description: Manage the webhooks of your application. - name: Domains description: Manage the domains of your application. - name: Config - Scopes description: Manage the scope configuration of your application. - name: Config - Claims description: Manage the claims mapping configuration of your application. - name: Config - Step-up description: Manage the step-up authentication configuration of your application. - name: Config - Migration description: Manage the user migration configuration of your application. - name: Config - Login OTP description: Manage the OTP login configuration of your application. - name: Config - Login OAuth description: Manage the OAuth login configuration of your application. - name: Config - Login SAML description: Manage the SAML 2.0 SSO connections of your application. - name: Config - Login Password description: Manage the password login configuration of your application. paths: /v2/session/apps/{appID}/config/login/saml/{providerID}/{connectionID}: parameters: - $ref: '#/components/parameters/appIDParam' - $ref: '#/components/parameters/samlProviderIDParam' - $ref: '#/components/parameters/samlConnectionIDParam' put: tags: - Config - Login SAML summary: Update SAML connection description: | Apply a partial update to a SAML connection. Omitted fields are left unchanged. The IdP `entity_id` is immutable — delete and recreate the connection to rotate it. operationId: updateSamlConnection requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PutSAMLConnectionRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SAMLConnectionSavedResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/InvalidRequestError' '404': description: Not Found content: application/json: schema: oneOf: - $ref: '#/components/schemas/AppNotFoundError' - $ref: '#/components/schemas/SAMLConnectionNotFoundError' components: parameters: appIDParam: in: path name: appID required: true description: The id of the app the request refers to. schema: $ref: '#/components/schemas/AppID' samlProviderIDParam: in: path name: providerID required: true description: The SAML provider identifier. schema: type: string examples: - okta - google - jumpcloud samlConnectionIDParam: in: path name: connectionID required: true description: The SAML connection identifier (prefixed with `samlc_`). schema: type: string examples: - samlc_01jqebhswje1ka1z7ahr9rfsgt schemas: PutSAMLConnectionRequest: type: object description: Partial update; omitted fields are left unchanged. properties: name: type: string enabled: type: boolean idp: $ref: '#/components/schemas/SAMLIdPConfigRequest' behavior: $ref: '#/components/schemas/SAMLBehavior' mapping: $ref: '#/components/schemas/SAMLAttributeMappingRequest' SAMLConnectionSavedResponse: type: object properties: connection: $ref: '#/components/schemas/SAMLConnectionResponse' required: - connection InvalidRequestError: type: object properties: code: type: string enum: - invalid_request examples: - invalid_request status: type: string enum: - bad_request examples: - bad_request message: type: string examples: - The request body is invalid. required: - code - status - message AppNotFoundError: type: object properties: code: type: string enum: - app_not_found examples: - app_not_found status: type: string enum: - not_found examples: - not_found message: type: string examples: - The application was not found. required: - code - status - message SAMLConnectionNotFoundError: type: object properties: code: type: string enum: - saml_connection_not_found examples: - saml_connection_not_found status: type: string enum: - not_found examples: - not_found message: type: string examples: - The requested SAML connection does not exist. required: - code - status - message AppID: type: string description: An application's unique identifier. examples: - 54e9ujn - fvua38g SAMLIdPConfigRequest: type: object description: | Explicit IdP block. Provide this only when you are not using `idp_metadata_url` or `idp_metadata_xml`. Certificates accept raw PEM or base64-wrapped PEM. properties: entity_id: type: string description: The IdP Entity ID (Issuer). Immutable after creation. examples: - http://www.okta.com/exk1fcia6d6EMsf331d8 sso_url: type: string description: The IdP Single Sign-On URL (HTTP-Redirect binding). examples: - https://acme.okta.com/app/abc/exk.../sso/saml slo_url: type: string description: The IdP Single Logout URL (optional). certificates: type: array items: type: string description: One or more IdP signing certificates (PEM or base64-wrapped PEM). required: - entity_id - sso_url - certificates SAMLBehavior: type: object properties: allow_email_account_merge: type: boolean examples: - true description: >- When `true`, links the SAML identifier to an existing user that already owns the same verified email. jit_provisioning: type: boolean examples: - true description: When `true`, just-in-time provisions a new user on first SSO login. email_domain_allowlist: type: array items: type: string examples: - - acme.com description: | Email domains this connection covers. The only domain→connection binding; required for email-resolved login and for `enforce_login`. enforce_login: type: boolean examples: - false description: | When `true`, email identifiers whose domain is in `email_domain_allowlist` must authenticate through this SAML connection — OTP and OAuth flows for those emails are refused with `saml_login_required`. Inert without a non-empty allowlist. default_redirect_uri: type: string examples: - https://app.acme.com/callback description: | Redirect URI used when an SP-initiated flow omits `redirect_uri`, and for all IdP-initiated logins. sync_profile_on_login: type: boolean examples: - false description: | When `true`, refreshes the IdP-owned profile attributes (`given_name`, `family_name`, and the assertion's groups stored under `samlgroups`) from the assertion on every SSO login rather than only at provisioning. The IdP becomes the source of truth for these fields and may overwrite values edited elsewhere. required: - allow_email_account_merge - jit_provisioning - enforce_login - default_redirect_uri - sync_profile_on_login SAMLAttributeMappingRequest: type: object description: >- Maps SAML assertion attributes to user profile fields. Defaults are applied per provider when omitted. properties: email: type: string examples: - email first_name: type: string examples: - first_name last_name: type: string examples: - last_name groups: type: string examples: - groups custom: type: object additionalProperties: type: string SAMLConnectionResponse: type: object properties: id: type: string examples: - samlc_01jqebhswje1ka1z7ahr9rfsgt provider_id: type: string examples: - okta name: type: string examples: - Acme Okta enabled: type: boolean examples: - true idp: $ref: '#/components/schemas/SAMLIdPConfigResponse' sp: $ref: '#/components/schemas/SAMLSPConfigResponse' behavior: $ref: '#/components/schemas/SAMLBehavior' mapping: $ref: '#/components/schemas/SAMLAttributeMappingResponse' created_at: type: string format: date-time examples: - '2025-03-15T10:30:00Z' updated_at: type: string format: date-time examples: - '2025-03-15T12:00:00Z' required: - id - provider_id - name - enabled - idp - sp - behavior - mapping - created_at - updated_at SAMLIdPConfigResponse: type: object properties: entity_id: type: string examples: - http://www.okta.com/exk1fcia6d6EMsf331d8 sso_url: type: string examples: - https://acme.okta.com/app/abc/exk.../sso/saml slo_url: type: string certificates: type: array items: type: string SAMLSPConfigResponse: type: object description: | Service Provider details, derived from the app domain and connection ID. Read-only; upload these to your Identity Provider. properties: entity_id: type: string description: The SP Entity ID (Audience URI). examples: - >- https://session.acme.com/v1/session/login/saml/okta/samlc_01jqebhswje1ka1z7ahr9rfsgt acs_url: type: string description: The Assertion Consumer Service (ACS) URL. examples: - >- https://session.acme.com/v1/session/login/saml/okta/samlc_01jqebhswje1ka1z7ahr9rfsgt/acs slo_url: type: string metadata_url: type: string description: Public SP metadata XML URL. examples: - >- https://session.acme.com/v1/session/login/saml/okta/samlc_01jqebhswje1ka1z7ahr9rfsgt/metadata signing_certificate: type: string description: >- SP X.509 signing certificate (PEM, base64); empty when SP signing is not in use. SAMLAttributeMappingResponse: type: object properties: email: type: string examples: - email given_name: type: string examples: - first_name family_name: type: string examples: - last_name groups: type: string examples: - groups custom: type: object additionalProperties: type: string securitySchemes: Authorization: type: http scheme: bearer ````