openapi: 3.2.0 info: title: n8n Public Settings SSO Saml API description: n8n Public API termsOfService: https://n8n.io/legal/#terms contact: email: hello@n8n.io license: name: Sustainable Use License url: https://github.com/n8n-io/n8n/blob/master/LICENSE.md version: 1.1.1 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: [] - CookieAuth: [] tags: - name: SettingsSsoSaml description: Operations about SAML SSO settings paths: /settings/sso/saml: get: x-eov-operation-id: getSamlConfiguration x-required-scope: saml:manage x-eov-operation-handler: v1/handlers/sso-saml/sso-saml.handler 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. responses: '200': description: Operation successful. content: application/json: schema: 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). example: https://n8n.example.com/rest/sso/saml/metadata returnUrl: type: string readOnly: true description: Assertion Consumer Service (ACS) return URL. example: https://n8n.example.com/rest/sso/saml/acs 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 `:`. 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. ' example: '**hidden**' 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. example: false loginBinding: type: string enum: - redirect - post description: SAML login request binding. example: redirect loginEnabled: type: boolean description: Whether SAML login is enabled. example: false loginLabel: type: string description: Label shown on the SAML login button. example: SAML authnRequestsSigned: type: boolean description: Whether authentication requests are signed. example: false wantAssertionsSigned: type: boolean description: Whether signed assertions are required. example: true wantMessageSigned: type: boolean description: Whether signed SAML messages are required. example: true 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. ' example: '**hidden**' 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. ' example: '**hidden**' acsBinding: type: string enum: - redirect - post description: Assertion Consumer Service binding. example: post signatureConfig: type: object description: Configuration for the signature in SAML requests and responses. additionalProperties: false required: - prefix - location properties: prefix: type: string example: ds location: type: object additionalProperties: false required: - reference - action properties: reference: type: string example: /samlp:Response/saml:Issuer action: type: string enum: - before - after - prepend - append example: after relayState: type: string description: Default relay state value for SAML requests. Use an empty string when unset. example: https://n8n.example.com '401': description: Unauthorized '403': description: Forbidden operationId: getSettingsSsoSaml x-operation-id-source: derived put: x-eov-operation-id: updateSamlConfiguration x-required-scope: saml:manage x-eov-operation-handler: v1/handlers/sso-saml/sso-saml.handler 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. requestBody: description: The full SAML SSO configuration to set. required: true content: application/json: schema: 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. ' 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 `:`. Use an empty array when unused. ' 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. ' metadataUrl: type: string description: 'URL to fetch identity provider metadata from. Use an empty string to clear a stored URL. ' ignoreSSL: type: boolean description: Whether to ignore SSL certificate errors when fetching metadata from a URL. example: false loginBinding: type: string enum: - redirect - post description: SAML login request binding. example: redirect loginEnabled: type: boolean description: Whether SAML login is enabled. example: false loginLabel: type: string description: Label shown on the SAML login button. example: SAML authnRequestsSigned: type: boolean description: Whether authentication requests are signed. example: false wantAssertionsSigned: type: boolean description: Whether signed assertions are required. example: true wantMessageSigned: type: boolean description: Whether signed SAML messages are required. example: true 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. ' 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. ' acsBinding: type: string enum: - redirect - post description: Assertion Consumer Service binding. example: post signatureConfig: type: object description: Configuration for the signature in SAML requests and responses. additionalProperties: false required: - prefix - location properties: prefix: type: string example: ds location: type: object additionalProperties: false required: - reference - action properties: reference: type: string example: /samlp:Response/saml:Issuer action: type: string enum: - before - after - prepend - append example: after relayState: type: string description: Default relay state value for SAML requests. Use an empty string when unused. example: https://n8n.example.com 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. ' example: https://n8n.example.com/rest/sso/saml/metadata 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. ' example: https://n8n.example.com/rest/sso/saml/acs responses: '200': description: Operation successful. content: application/json: schema: 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). example: https://n8n.example.com/rest/sso/saml/metadata returnUrl: type: string readOnly: true description: Assertion Consumer Service (ACS) return URL. example: https://n8n.example.com/rest/sso/saml/acs 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 `:`. 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. ' example: '**hidden**' 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. example: false loginBinding: type: string enum: - redirect - post description: SAML login request binding. example: redirect loginEnabled: type: boolean description: Whether SAML login is enabled. example: false loginLabel: type: string description: Label shown on the SAML login button. example: SAML authnRequestsSigned: type: boolean description: Whether authentication requests are signed. example: false wantAssertionsSigned: type: boolean description: Whether signed assertions are required. example: true wantMessageSigned: type: boolean description: Whether signed SAML messages are required. example: true 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. ' example: '**hidden**' 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. ' example: '**hidden**' acsBinding: type: string enum: - redirect - post description: Assertion Consumer Service binding. example: post signatureConfig: type: object description: Configuration for the signature in SAML requests and responses. additionalProperties: false required: - prefix - location properties: prefix: type: string example: ds location: type: object additionalProperties: false required: - reference - action properties: reference: type: string example: /samlp:Response/saml:Issuer action: type: string enum: - before - after - prepend - append example: after relayState: type: string description: Default relay state value for SAML requests. Use an empty string when unset. example: https://n8n.example.com '400': description: The request is invalid or provides malformed data. '401': description: Unauthorized '403': description: Forbidden '409': description: Conflict operationId: putSettingsSsoSaml x-operation-id-source: derived components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-N8N-API-KEY BearerAuth: type: http scheme: bearer bearerFormat: JWT CookieAuth: type: apiKey in: cookie name: n8n-auth externalDocs: description: n8n API documentation url: https://docs.n8n.io/api/ x-enable-proxy: false