SutraID|Developer Docs
QuickstartAPI ReferenceDashboard

SAML Identity Provider

SAML 2.0 Identity Provider endpoints — SutraID acts as the IdP, issuing signed assertions to external Service Providers via HTTP-Redirect and HTTP-POST bindings.

GET/api/v1/sso/saml-idp/:orgId/metadataGet SAML IdP metadata▾

Returns the SAML 2.0 IdP metadata XML document for the organization. Service Providers use this to configure trust with SutraID as the Identity Provider. The response includes the IdP entity ID, SSO service bindings (HTTP-Redirect and HTTP-POST), the X.509 signing certificate, and supported NameID formats.

Parameters

NameTypeRequiredDescription
orgIdstring (UUID)RequiredUnique identifier of the organization whose IdP metadata to retrieve.e.g. org_01hx9z1q2w3e4r5t6y7u

Response Fields

NameTypeRequiredDescription
EntityDescriptorXML elementOptionalRoot element containing the IdP metadata.
EntityDescriptor.entityIDstringOptionalUnique identifier (URI) of the Identity Provider.
IDPSSODescriptorXML elementOptionalDescribes the IdP SSO capabilities and protocol support.
KeyDescriptorXML elementOptionalContains the X.509 certificate used for signing SAML assertions.
NameIDFormatstringOptionalSupported NameID format (e.g. emailAddress).
SingleSignOnServiceXML elementOptionalSSO endpoint location and binding (HTTP-Redirect and HTTP-POST).

Response Example

{
  "_note": "Response is XML (application/samlmetadata+xml)",
  "_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<EntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\"\n  entityID=\"https://api.sutraid.com/api/v1/sso/saml-idp/org_01hx9z1q2w3e4r5t6y7u/metadata\">\n  <IDPSSODescriptor\n    WantAuthnRequestsSigned=\"false\"\n    protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\">\n    <KeyDescriptor use=\"signing\">\n      <ds:KeyInfo xmlns:ds=\"http://www.w3.org/2000/09/xmldsig#\">\n        <ds:X509Data>\n          <ds:X509Certificate>MIIC...base64-encoded-certificate...</ds:X509Certificate>\n        </ds:X509Data>\n      </ds:KeyInfo>\n    </KeyDescriptor>\n    <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>\n    <SingleSignOnService\n      Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\"\n      Location=\"https://api.sutraid.com/api/v1/sso/saml-idp/org_01hx9z1q2w3e4r5t6y7u/sso\"/>\n    <SingleSignOnService\n      Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\"\n      Location=\"https://api.sutraid.com/api/v1/sso/saml-idp/org_01hx9z1q2w3e4r5t6y7u/sso\"/>\n  </IDPSSODescriptor>\n</EntityDescriptor>"
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/sso/saml-idp/org_01hx9z1q2w3e4r5t6y7u/metadata"
GET/api/v1/sso/saml-idp/:orgId/ssoSSO endpoint (HTTP-Redirect binding)▾

Handles SP-initiated SAML SSO via the HTTP-Redirect binding. The Service Provider redirects the user to this endpoint with a deflated, base64-encoded SAMLRequest in the query string. If the user has an active session, SutraID validates the AuthnRequest, verifies user access to the requesting application, and returns an auto-submitting HTML form that POSTs a signed SAML Response to the SP Assertion Consumer Service URL. If the user is not authenticated, they are redirected to the SutraID login page and returned here after authentication.

Parameters

NameTypeRequiredDescription
orgIdstring (UUID)RequiredUnique identifier of the organization acting as the Identity Provider.e.g. org_01hx9z1q2w3e4r5t6y7u
SAMLRequeststringRequiredDeflated, base64-encoded SAML AuthnRequest XML generated by the Service Provider.e.g. fZJNT8MwDIb...deflated-base64-encoded...
RelayStatestringOptionalOpaque value relayed back to the Service Provider with the SAML Response. Typically the URL the user originally requested at the SP.e.g. https://sp.example.com/dashboard

Response Fields

NameTypeRequiredDescription
HTML formtext/htmlOptionalAuto-submitting HTML form that POSTs the SAMLResponse and RelayState to the SP ACS URL.
SAMLResponsestring (hidden input)OptionalBase64-encoded, signed SAML Response containing the assertion with user attributes.
RelayStatestring (hidden input)OptionalThe RelayState value passed through from the original request (if provided).

Response Example

{
  "_note": "Response is an auto-submitting HTML form (text/html)",
  "_html": "<!DOCTYPE html>\n<html>\n<head>\n  <title>SAML Response</title>\n</head>\n<body onload=\"document.forms[0].submit()\">\n  <form method=\"post\" action=\"https://sp.example.com/acs\">\n    <input type=\"hidden\" name=\"SAMLResponse\" value=\"PHNhbWxwOlJlc3BvbnNl...base64-encoded...\" />\n    <input type=\"hidden\" name=\"RelayState\" value=\"https://sp.example.com/dashboard\" />\n    <noscript>\n      <button type=\"submit\">Continue</button>\n    </noscript>\n  </form>\n</body>\n</html>"
}

Code Examples

# SP-initiated flow — typically triggered by the browser, not curl.
# This example shows the raw request structure.
curl -G "https://api.sutraid.com/api/v1/sso/saml-idp/org_01hx9z1q2w3e4r5t6y7u/sso" \
  --data-urlencode "SAMLRequest=fZJNT8MwDIb...deflated-base64..." \
  --data-urlencode "RelayState=https://sp.example.com/dashboard"
POST/api/v1/sso/saml-idp/:orgId/ssoSSO endpoint (HTTP-POST binding)▾

Handles SP-initiated SAML SSO via the HTTP-POST binding. The Service Provider submits a base64-encoded SAMLRequest in the POST body. If the user has an active session, SutraID validates the AuthnRequest, verifies user access to the requesting application, and returns an auto-submitting HTML form that POSTs a signed SAML Response to the SP Assertion Consumer Service URL. If the user is not authenticated, they are redirected to the SutraID login page and returned here after authentication.

Parameters

NameTypeRequiredDescription
orgIdstring (UUID)RequiredUnique identifier of the organization acting as the Identity Provider.e.g. org_01hx9z1q2w3e4r5t6y7u

Request Body

NameTypeRequiredDescription
SAMLRequeststringRequiredBase64-encoded SAML AuthnRequest XML generated by the Service Provider.e.g. PHNhbWxwOkF1dGhuUmVxdWVzdC...base64-encoded...
RelayStatestringOptionalOpaque value relayed back to the Service Provider with the SAML Response. Typically the URL the user originally requested at the SP.e.g. https://sp.example.com/dashboard

Response Fields

NameTypeRequiredDescription
HTML formtext/htmlOptionalAuto-submitting HTML form that POSTs the SAMLResponse and RelayState to the SP ACS URL.
SAMLResponsestring (hidden input)OptionalBase64-encoded, signed SAML Response containing the assertion with user attributes.
RelayStatestring (hidden input)OptionalThe RelayState value passed through from the original request (if provided).

Response Example

{
  "_note": "Response is an auto-submitting HTML form (text/html)",
  "_html": "<!DOCTYPE html>\n<html>\n<head>\n  <title>SAML Response</title>\n</head>\n<body onload=\"document.forms[0].submit()\">\n  <form method=\"post\" action=\"https://sp.example.com/acs\">\n    <input type=\"hidden\" name=\"SAMLResponse\" value=\"PHNhbWxwOlJlc3BvbnNl...base64-encoded...\" />\n    <input type=\"hidden\" name=\"RelayState\" value=\"https://sp.example.com/dashboard\" />\n    <noscript>\n      <button type=\"submit\">Continue</button>\n    </noscript>\n  </form>\n</body>\n</html>"
}

Code Examples

# SP-initiated flow — typically triggered by the browser, not curl.
# This example shows the raw request structure.
curl -X POST "https://api.sutraid.com/api/v1/sso/saml-idp/org_01hx9z1q2w3e4r5t6y7u/sso" \
  -d "SAMLRequest=PHNhbWxwOkF1dGhuUmVxdWVzdC...base64-encoded..." \
  -d "RelayState=https://sp.example.com/dashboard"