Create SSO provider

POST /app/sso/providers

Creates a new SSO provider and registers it as a Cognito identity provider. Requires the admin role and the SSO plan feature.

Each domain must be globally unique — a domain cannot be assigned to more than one provider across all organizations.
A provider may have 1–5 domains.
idpLogoutUrl is auto-extracted from SAML metadata or discovered from the OIDC discovery document on save.

Path parameters

None.

Request

See API Basics for required headers.

Request body — SAML

Field	Type	Required	Description
`providerType`	`"SAML"`	Yes	Must be `"SAML"`.
`name`	string	Yes	Display name for the provider. Max 100 characters.
`enabled`	boolean	No	Whether the provider is active. Defaults to `true`.
`domains`	string[]	Yes	1–5 email domains that route users to this provider (e.g. `"acme.com"`).
`samlMetadataXml`	string	Yes	The IdP federation metadata XML. Max 50,000 characters.

Request body — OIDC

Field	Type	Required	Description
`providerType`	`"OIDC"`	Yes	Must be `"OIDC"`.
`name`	string	Yes	Display name for the provider. Max 100 characters.
`enabled`	boolean	No	Whether the provider is active. Defaults to `true`.
`domains`	string[]	Yes	1–5 email domains that route users to this provider.
`oidc`	object	Yes	OIDC provider details. See below.

`oidc` object

Field	Type	Required	Description
`issuer`	string	Yes	Issuer URL of the identity provider (must be a valid HTTPS URL).
`clientId`	string	Yes	Client ID assigned by the IdP.
`clientSecret`	string	Yes	Client secret assigned by the IdP.
`authorizationEndpoint`	string	Yes	Authorization endpoint URL.
`tokenEndpoint`	string	Yes	Token endpoint URL.
`userInfoEndpoint`	string	Yes	UserInfo endpoint URL.
`jwksUri`	string	Yes	JWKS URI for verifying ID tokens.

Sample request — SAML

curl -X POST https://api.recomly.com/app/sso/providers \
  -H "Authorization: Bearer rk_live_abc123:def456" \
  -H "Content-Type: application/json" \
  -d '{
    "providerType": "SAML",
    "name": "Acme SAML",
    "domains": ["acme.com", "acme.org"],
    "samlMetadataXml": "<?xml version=\"1.0\"?>..."
  }'

Sample request — OIDC

curl -X POST https://api.recomly.com/app/sso/providers \
  -H "Authorization: Bearer rk_live_abc123:def456" \
  -H "Content-Type: application/json" \
  -d '{
    "providerType": "OIDC",
    "name": "Acme OIDC",
    "domains": ["internal.acme.com"],
    "oidc": {
      "issuer": "https://dev-12345678.okta.com",
      "clientId": "0oabc123def456ghi789",
      "clientSecret": "your-client-secret",
      "authorizationEndpoint": "https://dev-12345678.okta.com/oauth2/v1/authorize",
      "tokenEndpoint": "https://dev-12345678.okta.com/oauth2/v1/token",
      "userInfoEndpoint": "https://dev-12345678.okta.com/oauth2/v1/userinfo",
      "jwksUri": "https://dev-12345678.okta.com/oauth2/v1/keys"
    }
  }'

Sample response

Status: 201 Created

{
  "providerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Acme SAML",
  "providerType": "SAML",
  "cognitoProviderName": "PLATFORM-a1b2c3d4-ef123456",
  "enabled": true,
  "domains": ["acme.com", "acme.org"],
  "samlMetadataXml": "<?xml version=\"1.0\"?>...",
  "createdAt": "2026-01-10T12:00:00.000Z",
  "updatedAt": "2026-01-10T12:00:00.000Z"
}

For OIDC providers the response includes oidcIssuer and oidcClientId. Use Get SSO provider to retrieve the full configuration.

Error responses

See API Basics for standard status codes and error response format.

Status	Meaning
`400`	Validation error, or the SAML metadata is invalid or contains expired certificates. See `error` in the response body.
`403`	SSO feature not enabled on the plan.
`409`	One or more of the specified domains is already in use by another provider.

On this page