Settings Sso Saml

Operations about SAML SSO settings

Retrieve the SAML SSO configuration

get

/settings/sso/saml

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.

Authorizations

X-N8N-API-KEYstringRequired

Responses

200

Operation successful.

application/json

entityIDstringRead-onlyRequired

Service provider entity ID (metadata URL).

Example: https://n8n.example.com/rest/sso/saml/metadata

returnUrlstringRead-onlyRequired

Assertion Consumer Service (ACS) return URL.

Example: https://n8n.example.com/rest/sso/saml/acs

metadatastringRequired

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**

metadataUrlstringRequired

URL to fetch identity provider metadata from. Use an empty string when unset.

ignoreSSLbooleanRequired

Whether to ignore SSL certificate errors when fetching metadata from a URL.

Example: false

loginBindingstring · enumRequired

SAML login request binding.

Example: redirectPossible values:

loginEnabledbooleanRequired

Whether SAML login is enabled.

Example: false

loginLabelstringRequired

Label shown on the SAML login button.

Example: SAML

authnRequestsSignedbooleanRequired

Whether authentication requests are signed.

Example: false

wantAssertionsSignedbooleanRequired

Whether signed assertions are required.

Example: true

wantMessageSignedbooleanRequired

Whether signed SAML messages are required.

Example: true

signingPrivateKeystringRequired

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**

signingCertificatestringRequired

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**

acsBindingstring · enumRequired

Assertion Consumer Service binding.

Example: postPossible values:

relayStatestringRequired

Default relay state value for SAML requests. Use an empty string when unset.

Example: https://n8n.example.com

401

Unauthorized

403

Forbidden

get/settings/sso/saml

GET /api/v1/settings/sso/saml HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "entityID": "https://n8n.example.com/rest/sso/saml/metadata",
  "returnUrl": "https://n8n.example.com/rest/sso/saml/acs",
  "mapping": {
    "email": "text",
    "firstName": "text",
    "lastName": "text",
    "userPrincipalName": "text",
    "n8nInstanceRole": "text",
    "n8nProjectRoles": [
      "text"
    ]
  },
  "metadata": "**hidden**",
  "metadataUrl": "text",
  "ignoreSSL": false,
  "loginBinding": "redirect",
  "loginEnabled": false,
  "loginLabel": "SAML",
  "authnRequestsSigned": false,
  "wantAssertionsSigned": true,
  "wantMessageSigned": true,
  "signingPrivateKey": "**hidden**",
  "signingCertificate": "**hidden**",
  "acsBinding": "post",
  "signatureConfig": {
    "prefix": "ds",
    "location": {
      "reference": "/samlp:Response/saml:Issuer",
      "action": "after"
    }
  },
  "relayState": "https://n8n.example.com"
}

Set the SAML SSO configuration

put

/settings/sso/saml

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.

Authorizations

X-N8N-API-KEYstringRequired

Body

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.

metadatastringRequired

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.

metadataUrlstringRequired

URL to fetch identity provider metadata from. Use an empty string to clear a stored URL.

ignoreSSLbooleanRequired

Whether to ignore SSL certificate errors when fetching metadata from a URL.

Example: false

loginBindingstring · enumRequired

SAML login request binding.

Example: redirectPossible values:

loginEnabledbooleanRequired

Whether SAML login is enabled.

Example: false

loginLabelstringRequired

Label shown on the SAML login button.

Example: SAML

authnRequestsSignedbooleanRequired

Whether authentication requests are signed.

Example: false

wantAssertionsSignedbooleanRequired

Whether signed assertions are required.

Example: true

wantMessageSignedbooleanRequired

Whether signed SAML messages are required.

Example: true

signingPrivateKeystringRequired

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.

signingCertificatestringRequired

PEM-encoded certificate containing the public key matching the signing private key. Use an empty string when unused or to clear an existing certificate.

acsBindingstring · enumRequired

Assertion Consumer Service binding.

Example: postPossible values:

relayStatestringRequired

Default relay state value for SAML requests. Use an empty string when unused.

Example: https://n8n.example.com

entityIDstringOptional

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

returnUrlstringOptional

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

Operation successful.

application/json

entityIDstringRead-onlyRequired

Service provider entity ID (metadata URL).

Example: https://n8n.example.com/rest/sso/saml/metadata

returnUrlstringRead-onlyRequired

Assertion Consumer Service (ACS) return URL.

Example: https://n8n.example.com/rest/sso/saml/acs

metadatastringRequired

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**

metadataUrlstringRequired

URL to fetch identity provider metadata from. Use an empty string when unset.

ignoreSSLbooleanRequired

Whether to ignore SSL certificate errors when fetching metadata from a URL.

Example: false

loginBindingstring · enumRequired

SAML login request binding.

Example: redirectPossible values:

loginEnabledbooleanRequired

Whether SAML login is enabled.

Example: false

loginLabelstringRequired

Label shown on the SAML login button.

Example: SAML

authnRequestsSignedbooleanRequired

Whether authentication requests are signed.

Example: false

wantAssertionsSignedbooleanRequired

Whether signed assertions are required.

Example: true

wantMessageSignedbooleanRequired

Whether signed SAML messages are required.

Example: true

signingPrivateKeystringRequired

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**

signingCertificatestringRequired

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**

acsBindingstring · enumRequired

Assertion Consumer Service binding.

Example: postPossible values:

relayStatestringRequired

Default relay state value for SAML requests. Use an empty string when unset.

Example: https://n8n.example.com

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

409

Conflict

put/settings/sso/saml

PUT /api/v1/settings/sso/saml HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 685

{
  "mapping": {
    "email": "text",
    "firstName": "text",
    "lastName": "text",
    "userPrincipalName": "text",
    "n8nInstanceRole": "text",
    "n8nProjectRoles": [
      "text"
    ]
  },
  "metadata": "text",
  "metadataUrl": "text",
  "ignoreSSL": false,
  "loginBinding": "redirect",
  "loginEnabled": false,
  "loginLabel": "SAML",
  "authnRequestsSigned": false,
  "wantAssertionsSigned": true,
  "wantMessageSigned": true,
  "signingPrivateKey": "text",
  "signingCertificate": "text",
  "acsBinding": "post",
  "signatureConfig": {
    "prefix": "ds",
    "location": {
      "reference": "/samlp:Response/saml:Issuer",
      "action": "after"
    }
  },
  "relayState": "https://n8n.example.com",
  "entityID": "https://n8n.example.com/rest/sso/saml/metadata",
  "returnUrl": "https://n8n.example.com/rest/sso/saml/acs"
}

{
  "entityID": "https://n8n.example.com/rest/sso/saml/metadata",
  "returnUrl": "https://n8n.example.com/rest/sso/saml/acs",
  "mapping": {
    "email": "text",
    "firstName": "text",
    "lastName": "text",
    "userPrincipalName": "text",
    "n8nInstanceRole": "text",
    "n8nProjectRoles": [
      "text"
    ]
  },
  "metadata": "**hidden**",
  "metadataUrl": "text",
  "ignoreSSL": false,
  "loginBinding": "redirect",
  "loginEnabled": false,
  "loginLabel": "SAML",
  "authnRequestsSigned": false,
  "wantAssertionsSigned": true,
  "wantMessageSigned": true,
  "signingPrivateKey": "**hidden**",
  "signingCertificate": "**hidden**",
  "acsBinding": "post",
  "signatureConfig": {
    "prefix": "ds",
    "location": {
      "reference": "/samlp:Response/saml:Issuer",
      "action": "after"
    }
  },
  "relayState": "https://n8n.example.com"
}