SP Metadata Endpoint

The EK backend exposes a public SAML Service Provider (SP) metadata endpoint that Identity Providers (IdPs) can consume to automatically establish trust with the application. This removes the need for administrators to manually exchange SP configuration details during SSO setup.

Endpoint

GET /saml/well-known/sp-metadata

Property	Value
Authentication	None (publicly accessible)
Content-Type	`application/samlmetadata+xml`
Content-Disposition	`inline; filename="sp_metadata.xml"`

Purpose

When configuring SAML SSO between an IdP (e.g., Okta, Azure AD, OneLogin) and EK, the IdP needs to know several things about the SP:

Entity ID — a unique identifier for the SP.
Assertion Consumer Service (ACS) URL — where the IdP should POST SAML responses.
Supported NameID format — how the IdP should identify the user.
Signing certificate (if applicable) — the public key the IdP can use to verify signed AuthnRequests.

Rather than requiring an administrator to copy-paste each of these values individually, this endpoint provides them all in a single standards-compliant SAML 2.0 metadata XML document. Administrators can either point their IdP directly at this URL or download the XML and upload it to the IdP. For step-by-step instructions on how to use this endpoint during setup, see the SSO Metadata Setup Guide.

Response Format

The endpoint returns a SAML 2.0 EntityDescriptor document. Below is a representative example:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     entityID="https://api.example.com/user/generic/sso/saml/acs/admin">
  <md:SPSSODescriptor AuthnRequestsSigned="true"
                      WantAssertionsSigned="true"
                      protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
          <ds:X509Certificate>MIIC...base64-encoded-cert...</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                Location="https://api.example.com/user/generic/sso/saml/acs/admin"
                                index="0"
                                isDefault="true" />
  </md:SPSSODescriptor>
</md:EntityDescriptor>

Guaranteed vs. Optional Components

Guaranteed (always present)

XML Element / Attribute	Description
`<md:EntityDescriptor entityID="...">`	The SP entity ID. Defaults to the ACS URL unless `CUSTOM_ENTITY_ID_FOR_GENERIC_SSO` is set, in which case that value is used instead.
`<md:SPSSODescriptor>`	Container for all SP SSO descriptor information. Always includes `WantAssertionsSigned="true"` and `protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"`.
`AuthnRequestsSigned` attribute	Always present on `SPSSODescriptor`. Set to `"true"` when an SP signing certificate is configured, `"false"` otherwise.
`<md:NameIDFormat>`	Always `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`. EK expects the IdP to provide the user’s email address as the NameID.
`<md:AssertionConsumerService>`	The ACS endpoint. Always uses HTTP-POST binding, index `0`, and `isDefault="true"`. The `Location` is derived from the EK backend root URL: `{BACKEND_ROOT_URL}/user/generic/sso/saml/acs/admin`.

Optional (conditionally present)

XML Element / Attribute	Condition	Description
`<md:KeyDescriptor use="signing">`	Present only when the server is configured with a valid SP signing certificate and key via `SAML_SP_CERT_FILE` and `SAML_SP_KEY_FILE`.	Contains the SP’s X.509 signing certificate so the IdP can verify signed AuthnRequests. When absent, AuthnRequests are sent unsigned and `AuthnRequestsSigned` is `"false"`.

Variable	Effect on Metadata
`CUSTOM_ENTITY_ID_FOR_GENERIC_SSO`	If set, overrides the default `entityID` (which is the ACS URL).
`SAML_SP_CERT_FILE`	Path to the SP’s PEM-encoded X.509 certificate. When set alongside `SAML_SP_KEY_FILE`, the `KeyDescriptor` block is included and `AuthnRequestsSigned` becomes `"true"`.
`SAML_SP_KEY_FILE`	Path to the SP’s PEM-encoded private key. Required alongside `SAML_SP_CERT_FILE` for request signing to be enabled.

Get Started!

Offerings

Chat

Agents

Knowledge Base

Workflows

Interfaces

Public Chatbot

Project Settings

My Account

Platform Admin

SDK

General Information

Change Logs

Endpoint

Purpose

Response Format

Guaranteed vs. Optional Components

Guaranteed (always present)

Optional (conditionally present)

​Endpoint

​Purpose

​Response Format

​Guaranteed vs. Optional Components

​Guaranteed (always present)

​Optional (conditionally present)

​Related Environment Variables

Endpoint

Purpose

Response Format

Guaranteed vs. Optional Components

Guaranteed (always present)

Optional (conditionally present)

Related Environment Variables