Settings Sso Saml

{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"SettingsSsoSaml","description":"Operations about SAML SSO settings"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"saml-configuration":{"type":"object","additionalProperties":false,"required":["entityID","returnUrl","mapping","metadata","metadataUrl","ignoreSSL","loginBinding","loginEnabled","loginLabel","authnRequestsSigned","wantAssertionsSigned","wantMessageSigned","signingPrivateKey","signingCertificate","acsBinding","signatureConfig","relayState"],"properties":{"entityID":{"type":"string","readOnly":true,"description":"Service provider entity ID (metadata URL)."},"returnUrl":{"type":"string","readOnly":true,"description":"Assertion Consumer Service (ACS) return URL."},"mapping":{"type":"object","description":"Mapping of SAML attributes to n8n user fields.","additionalProperties":false,"required":["email","firstName","lastName","userPrincipalName","n8nInstanceRole","n8nProjectRoles"],"properties":{"email":{"type":"string","description":"SAML attribute mapped to the user's email."},"firstName":{"type":"string","description":"SAML attribute mapped to the user's first name."},"lastName":{"type":"string","description":"SAML attribute mapped to the user's last name."},"userPrincipalName":{"type":"string","description":"SAML attribute mapped to the user's principal name."},"n8nInstanceRole":{"type":"string","description":"SAML attribute mapped to the n8n instance role."},"n8nProjectRoles":{"type":"array","items":{"type":"string"},"description":"SAML attributes mapped to n8n project roles, formatted as `<projectId>:<role>`."}}},"metadata":{"type":"string","description":"Identity provider metadata in XML format. Redacted on read when set because it contains IdP certificates; never echoed back in plaintext. Use an empty string when unset.\n"},"metadataUrl":{"type":"string","description":"URL to fetch identity provider metadata from. Use an empty string when unset."},"ignoreSSL":{"type":"boolean","description":"Whether to ignore SSL certificate errors when fetching metadata from a URL."},"loginBinding":{"type":"string","enum":["redirect","post"],"description":"SAML login request binding."},"loginEnabled":{"type":"boolean","description":"Whether SAML login is enabled."},"loginLabel":{"type":"string","description":"Label shown on the SAML login button."},"authnRequestsSigned":{"type":"boolean","description":"Whether authentication requests are signed."},"wantAssertionsSigned":{"type":"boolean","description":"Whether signed assertions are required."},"wantMessageSigned":{"type":"boolean","description":"Whether signed SAML messages are required."},"signingPrivateKey":{"type":"string","description":"PEM-encoded private key for signing SAML AuthnRequests. Redacted on read when set; never echoed back in plaintext. Use an empty string when unset.\n"},"signingCertificate":{"type":"string","description":"PEM-encoded certificate containing the public key matching the signing private key. Redacted on read when set; never echoed back in plaintext. Use an empty string when unset.\n"},"acsBinding":{"type":"string","enum":["redirect","post"],"description":"Assertion Consumer Service binding."},"signatureConfig":{"type":"object","description":"Configuration for the signature in SAML requests and responses.","additionalProperties":false,"required":["prefix","location"],"properties":{"prefix":{"type":"string"},"location":{"type":"object","additionalProperties":false,"required":["reference","action"],"properties":{"reference":{"type":"string"},"action":{"type":"string","enum":["before","after","prepend","append"]}}}}},"relayState":{"type":"string","description":"Default relay state value for SAML requests. Use an empty string when unset."}}}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"}}},"paths":{"/settings/sso/saml":{"get":{"tags":["SettingsSsoSaml"],"summary":"Retrieve the SAML SSO configuration","description":"Retrieve the current SAML SSO configuration, including every field exposed in the UI plus the service provider entity ID and ACS return URL. Signing private keys, signing certificates, and identity provider metadata are redacted on read. Requires the `saml:manage` scope and the SAML feature to be licensed.\n","responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/saml-configuration"}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"}}}}}}

{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"SettingsSsoSaml","description":"Operations about SAML SSO settings"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","variables":{"url":{"default":"https://example.com"}}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"saml-configuration.update":{"type":"object","additionalProperties":false,"description":"Full SAML SSO configuration. Every field must be provided; use empty strings or empty arrays when a value is unset. Partial updates are not supported.\n","required":["mapping","metadata","metadataUrl","ignoreSSL","loginBinding","loginEnabled","loginLabel","authnRequestsSigned","wantAssertionsSigned","wantMessageSigned","signingPrivateKey","signingCertificate","acsBinding","signatureConfig","relayState"],"properties":{"mapping":{"type":"object","description":"Mapping of SAML attributes to n8n user fields. Use empty strings / empty arrays for unused attributes.","additionalProperties":false,"required":["email","firstName","lastName","userPrincipalName","n8nInstanceRole","n8nProjectRoles"],"properties":{"email":{"type":"string","description":"SAML attribute mapped to the user's email."},"firstName":{"type":"string","description":"SAML attribute mapped to the user's first name."},"lastName":{"type":"string","description":"SAML attribute mapped to the user's last name."},"userPrincipalName":{"type":"string","description":"SAML attribute mapped to the user's principal name."},"n8nInstanceRole":{"type":"string","description":"SAML attribute mapped to the n8n instance role. Use an empty string when unused."},"n8nProjectRoles":{"type":"array","items":{"type":"string"},"description":"SAML attributes mapped to n8n project roles, formatted as `<projectId>:<role>`. Use an empty array when unused.\n"}}},"metadata":{"type":"string","description":"Identity provider metadata in XML format. Use an empty string to clear stored metadata (also clears metadataUrl when no URL is provided). Use the redaction placeholder from a prior GET to leave an existing value unchanged.\n"},"metadataUrl":{"type":"string","description":"URL to fetch identity provider metadata from. Use an empty string to clear a stored URL.\n"},"ignoreSSL":{"type":"boolean","description":"Whether to ignore SSL certificate errors when fetching metadata from a URL."},"loginBinding":{"type":"string","enum":["redirect","post"],"description":"SAML login request binding."},"loginEnabled":{"type":"boolean","description":"Whether SAML login is enabled."},"loginLabel":{"type":"string","description":"Label shown on the SAML login button."},"authnRequestsSigned":{"type":"boolean","description":"Whether authentication requests are signed."},"wantAssertionsSigned":{"type":"boolean","description":"Whether signed assertions are required."},"wantMessageSigned":{"type":"boolean","description":"Whether signed SAML messages are required."},"signingPrivateKey":{"type":"string","description":"PEM-encoded private key for signing SAML AuthnRequests. Use an empty string to clear an existing key, or the redaction placeholder from a prior GET to leave it unchanged.\n"},"signingCertificate":{"type":"string","description":"PEM-encoded certificate containing the public key matching the signing private key. Use an empty string when unused or to clear an existing certificate.\n"},"acsBinding":{"type":"string","enum":["redirect","post"],"description":"Assertion Consumer Service binding."},"signatureConfig":{"type":"object","description":"Configuration for the signature in SAML requests and responses.","additionalProperties":false,"required":["prefix","location"],"properties":{"prefix":{"type":"string"},"location":{"type":"object","additionalProperties":false,"required":["reference","action"],"properties":{"reference":{"type":"string"},"action":{"type":"string","enum":["before","after","prepend","append"]}}}}},"relayState":{"type":"string","description":"Default relay state value for SAML requests. Use an empty string when unused."},"entityID":{"type":"string","description":"Service provider entity ID. Returned by GET for convenience; ignored on write so a GET response can be sent back as a PUT body.\n"},"returnUrl":{"type":"string","description":"Assertion Consumer Service return URL. Returned by GET for convenience; ignored on write so a GET response can be sent back as a PUT body.\n"}}},"saml-configuration":{"type":"object","additionalProperties":false,"required":["entityID","returnUrl","mapping","metadata","metadataUrl","ignoreSSL","loginBinding","loginEnabled","loginLabel","authnRequestsSigned","wantAssertionsSigned","wantMessageSigned","signingPrivateKey","signingCertificate","acsBinding","signatureConfig","relayState"],"properties":{"entityID":{"type":"string","readOnly":true,"description":"Service provider entity ID (metadata URL)."},"returnUrl":{"type":"string","readOnly":true,"description":"Assertion Consumer Service (ACS) return URL."},"mapping":{"type":"object","description":"Mapping of SAML attributes to n8n user fields.","additionalProperties":false,"required":["email","firstName","lastName","userPrincipalName","n8nInstanceRole","n8nProjectRoles"],"properties":{"email":{"type":"string","description":"SAML attribute mapped to the user's email."},"firstName":{"type":"string","description":"SAML attribute mapped to the user's first name."},"lastName":{"type":"string","description":"SAML attribute mapped to the user's last name."},"userPrincipalName":{"type":"string","description":"SAML attribute mapped to the user's principal name."},"n8nInstanceRole":{"type":"string","description":"SAML attribute mapped to the n8n instance role."},"n8nProjectRoles":{"type":"array","items":{"type":"string"},"description":"SAML attributes mapped to n8n project roles, formatted as `<projectId>:<role>`."}}},"metadata":{"type":"string","description":"Identity provider metadata in XML format. Redacted on read when set because it contains IdP certificates; never echoed back in plaintext. Use an empty string when unset.\n"},"metadataUrl":{"type":"string","description":"URL to fetch identity provider metadata from. Use an empty string when unset."},"ignoreSSL":{"type":"boolean","description":"Whether to ignore SSL certificate errors when fetching metadata from a URL."},"loginBinding":{"type":"string","enum":["redirect","post"],"description":"SAML login request binding."},"loginEnabled":{"type":"boolean","description":"Whether SAML login is enabled."},"loginLabel":{"type":"string","description":"Label shown on the SAML login button."},"authnRequestsSigned":{"type":"boolean","description":"Whether authentication requests are signed."},"wantAssertionsSigned":{"type":"boolean","description":"Whether signed assertions are required."},"wantMessageSigned":{"type":"boolean","description":"Whether signed SAML messages are required."},"signingPrivateKey":{"type":"string","description":"PEM-encoded private key for signing SAML AuthnRequests. Redacted on read when set; never echoed back in plaintext. Use an empty string when unset.\n"},"signingCertificate":{"type":"string","description":"PEM-encoded certificate containing the public key matching the signing private key. Redacted on read when set; never echoed back in plaintext. Use an empty string when unset.\n"},"acsBinding":{"type":"string","enum":["redirect","post"],"description":"Assertion Consumer Service binding."},"signatureConfig":{"type":"object","description":"Configuration for the signature in SAML requests and responses.","additionalProperties":false,"required":["prefix","location"],"properties":{"prefix":{"type":"string"},"location":{"type":"object","additionalProperties":false,"required":["reference","action"],"properties":{"reference":{"type":"string"},"action":{"type":"string","enum":["before","after","prepend","append"]}}}}},"relayState":{"type":"string","description":"Default relay state value for SAML requests. Use an empty string when unset."}}}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"conflict":{"description":"Conflict"}}},"paths":{"/settings/sso/saml":{"put":{"tags":["SettingsSsoSaml"],"summary":"Set the SAML SSO configuration","description":"Replace the SAML SSO configuration with the provided full object. Every writable field must be sent; use empty strings or empty arrays when a value is unset. Read-only `entityID` / `returnUrl` from GET are ignored if included, so a GET response can be sent back as a PUT body. Redacted secret placeholders keep the stored values unchanged. The update takes effect exactly as it would from the UI, using the same validation. Requires the `saml:manage` scope and the SAML feature to be licensed. When the configuration is managed via environment variables, the write is rejected with 409 and no changes are made.\n","requestBody":{"description":"The full SAML SSO configuration to set.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/saml-configuration.update"}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/saml-configuration"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"409":{"$ref":"#/components/responses/conflict"}}}}}}