SAML single sign-on

SyAuth is the identity provider (IdP). Register your service provider (SP) using its Entity ID and Assertion Consumer Service URL, then import SyAuth metadata into the SP. Check availability before rollout.

API conventions · All endpoints · Schemas

/e/v1/saml/metadata/

Publish the configured SAML IdP metadata XML.

Availability note: standalone access with the credential described below has a known authentication limitation. Check integration availability before relying on this operation. If it returns an unexpected 401, contact support with the endpoint and sanitized response.

GET

No body. Returns IdP metadata XML. A 503 means SAML is not available for this deployment; contact support before configuring your service provider.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — text/XML

HTML or text/XML response; do not parse as JSON.

503 — text/XML

HTML or text/XML response; do not parse as JSON.

/e/v1/saml/sso/

Accept an SP-initiated AuthnRequest.

Availability note: standalone access with the credential described below has a known authentication limitation. Check integration availability before relying on this operation. If it returns an unexpected 401, contact support with the endpoint and sanitized response.

GET

HTTP-Redirect binding: required SAMLRequest query (Base64/DEFLATE encoded XML), optional RelayState. Registered active SP and matching ACS required.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	SAMLRequest	''
query	RelayState	''

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — html

HTML or text/XML response; do not parse as JSON.

302 — redirect

Redirect: inspect Location and preserve cookies.

400 — text/XML

HTML or text/XML response; do not parse as JSON.

500 — text/XML

HTML or text/XML response; do not parse as JSON.

POST

HTTP-POST form binding: required Base64 SAMLRequest; optional RelayState. If login is needed, pending request is saved in the session. Success is an HTML form posting SAMLResponse to the SP, not JSON.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
form	SAMLRequest	''
form	RelayState	''

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — html

HTML or text/XML response; do not parse as JSON.

302 — redirect

Redirect: inspect Location and preserve cookies.

400 — text/XML

HTML or text/XML response; do not parse as JSON.

500 — text/XML

HTML or text/XML response; do not parse as JSON.

/e/v1/saml/sso/finish/

Resume SAML after hosted login.

Availability note: standalone access with the credential described below has a known authentication limitation. Check integration availability before relying on this operation. If it returns an unexpected 401, contact support with the endpoint and sanitized response.

GET

No request payload; requires pending SAML request in the same browser session. Missing pending request returns 400 text.

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — html

HTML or text/XML response; do not parse as JSON.

302 — redirect

Redirect: inspect Location and preserve cookies.

400 — text/XML

HTML or text/XML response; do not parse as JSON.

500 — text/XML

HTML or text/XML response; do not parse as JSON.

/e/v1/developer/saml/sps/

Manage SAML relying parties for a workspace.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_saml.

Required query workspace_id UUID.

Request fields (combine with the requirements and schema above):

Location	Field	Fallback when absent
query	workspace_id	not supplied

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "results": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "workspace_id": "EXAMPLE_WORKSPACE_ID",
      "name": "Example",
      "sp_entity_id": "EXAMPLE_SP_ENTITY_ID",
      "acs_url": "EXAMPLE_ACS_URL",
      "name_id_format": "EXAMPLE_NAME_ID_FORMAT",
      "name_id_attribute": "EXAMPLE_NAME_ID_ATTRIBUTE",
      "sign_assertions": true,
      "attribute_mapping": "EXAMPLE_ATTRIBUTE_MAPPING",
      "default_relay_state": "EXAMPLE_DEFAULT_RELAY_STATE",
      "has_sp_cert": true,
      "is_active": true,
      "created_by": "EXAMPLE_CREATED_BY",
      "created_at": "EXAMPLE_CREATED_AT",
      "updated_at": "EXAMPLE_UPDATED_AT"
    }
  ]
}

400 — json

{
  "error": "workspace_id is required"
}

403 — json

{
  "error": "Forbidden"
}

POST

Required developer-token scope: write_saml.

Required JSON workspace_id (workspace alias accepted), name, sp_entity_id, acs_url strings. Optional name_id_format, name_id_attribute, sign_assertions boolean, sp_cert_pem string, attribute_mapping object, default_relay_state string, is_active boolean.

Example request body:

{
  "workspace_id": "11111111-1111-4111-8111-111111111111",
  "name": "Example SP",
  "sp_entity_id": "https://sp.example.test/metadata",
  "acs_url": "https://sp.example.test/acs",
  "sign_assertions": true
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

201 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "workspace_id": "EXAMPLE_WORKSPACE_ID",
  "name": "Example",
  "sp_entity_id": "EXAMPLE_SP_ENTITY_ID",
  "acs_url": "EXAMPLE_ACS_URL",
  "name_id_format": "EXAMPLE_NAME_ID_FORMAT",
  "name_id_attribute": "EXAMPLE_NAME_ID_ATTRIBUTE",
  "sign_assertions": true,
  "attribute_mapping": "EXAMPLE_ATTRIBUTE_MAPPING",
  "default_relay_state": "EXAMPLE_DEFAULT_RELAY_STATE",
  "has_sp_cert": true,
  "is_active": true,
  "created_by": "EXAMPLE_CREATED_BY",
  "created_at": "EXAMPLE_CREATED_AT",
  "updated_at": "EXAMPLE_UPDATED_AT"
}

400 — json

{
  "error": "workspace_id is required"
}

400 — json

{
  "error": "Missing required fields: EXAMPLE"
}

403 — json

{
  "error": "Forbidden"
}

/e/v1/developer/saml/sps/{sp_id}/

Read, update or delete a configured SAML service provider.

Authentication: X-Developer-Token with the scope shown below, an active SyAuth plan, and access to the resource. Dashboard requests use your signed-in account.

GET

Required developer-token scope: read_saml.

Must have access to its workspace.

Path parameters: sp_id (uuid, required).

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "workspace_id": "EXAMPLE_WORKSPACE_ID",
  "name": "Example",
  "sp_entity_id": "EXAMPLE_SP_ENTITY_ID",
  "acs_url": "EXAMPLE_ACS_URL",
  "name_id_format": "EXAMPLE_NAME_ID_FORMAT",
  "name_id_attribute": "EXAMPLE_NAME_ID_ATTRIBUTE",
  "sign_assertions": true,
  "attribute_mapping": "EXAMPLE_ATTRIBUTE_MAPPING",
  "default_relay_state": "EXAMPLE_DEFAULT_RELAY_STATE",
  "has_sp_cert": true,
  "is_active": true,
  "created_by": "EXAMPLE_CREATED_BY",
  "created_at": "EXAMPLE_CREATED_AT",
  "updated_at": "EXAMPLE_UPDATED_AT"
}

404 — json

{
  "error": "Not found"
}

PUT

Required developer-token scope: write_saml.

Partial writable fields from the create contract; workspace is not reassigned. No PATCH route is mounted.

Path parameters: sp_id (uuid, required).

Example request body:

{
  "name": "Renamed SP",
  "is_active": false
}

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

200 — json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "workspace_id": "EXAMPLE_WORKSPACE_ID",
  "name": "Example",
  "sp_entity_id": "EXAMPLE_SP_ENTITY_ID",
  "acs_url": "EXAMPLE_ACS_URL",
  "name_id_format": "EXAMPLE_NAME_ID_FORMAT",
  "name_id_attribute": "EXAMPLE_NAME_ID_ATTRIBUTE",
  "sign_assertions": true,
  "attribute_mapping": "EXAMPLE_ATTRIBUTE_MAPPING",
  "default_relay_state": "EXAMPLE_DEFAULT_RELAY_STATE",
  "has_sp_cert": true,
  "is_active": true,
  "created_by": "EXAMPLE_CREATED_BY",
  "created_at": "EXAMPLE_CREATED_AT",
  "updated_at": "EXAMPLE_UPDATED_AT"
}

404 — json

{
  "error": "Not found"
}

DELETE

Required developer-token scope: write_saml.

No body. Deletes the SP configuration.

Path parameters: sp_id (uuid, required).

Success and error response examples

Illustrative values; conditional branches are alternatives. Fields vary with the operation and account configuration.

204 — json

No response body.

404 — json

{
  "error": "Not found"
}