SutraID|Developer Docs
QuickstartAPI ReferenceDashboard

Applications

OIDC and SAML application management, OAuth 2.0 token operations, and dynamic client registration.

POST/api/v1/organizations/:orgId/applicationsCreate ApplicationBearer Token▾

Create a new OIDC or SAML application within an organization. Returns the newly created application record including the generated clientId and clientSecret.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hxyz

Request Body

NameTypeRequiredDescription
namestringRequiredDisplay name of the application (max 100 characters).e.g. My Web App
descriptionstringOptionalOptional description of the application (max 500 characters).e.g. Customer-facing web application.
logoUrlstringOptionalURL of the application logo.e.g. https://cdn.example.com/logo.png
typestringRequiredProtocol type of the application.e.g. OIDC
OIDCSAML
redirectUrisstring[]OptionalAllowed redirect URIs for OAuth 2.0 / OIDC flows.e.g. ["https://app.example.com/callback"]
grantTypesstring[]OptionalAllowed OAuth 2.0 grant types.e.g. ["authorization_code", "refresh_token"]
responseTypesstring[]OptionalAllowed OAuth 2.0 response types.e.g. ["code"]
scopesstring[]OptionalAllowed OAuth 2.0 / OIDC scopes.e.g. ["openid", "profile", "email"]
tokenEndpointAuthMethodstringOptionalClient authentication method at the token endpoint.e.g. client_secret_post
isPublicClientbooleanOptionalWhether the application is a public client (e.g. SPA or mobile app).e.g. false
requireDpopbooleanOptionalWhether Demonstrating Proof-of-Possession (DPoP) is required.e.g. false
jwksobjectOptionalJSON Web Key Set for the application.e.g. {"keys": [...]}
dpopNonceEnabledbooleanOptionalWhether DPoP nonce checking is enabled.e.g. false
isAiAgentbooleanOptionalWhether this application represents an AI agent.e.g. false
samlEntityIdstringOptionalSAML IdP entity ID (required for SAML applications).e.g. https://sutraid.com/saml/idp
samlSpEntityIdstringOptionalSAML Service Provider entity ID.e.g. https://app.example.com/saml/sp
samlSpAcsUrlstringOptionalSAML Assertion Consumer Service URL.e.g. https://app.example.com/saml/acs
samlNameIdFormatstringOptionalSAML NameID format.e.g. urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
samlAttributeMappingobjectOptionalMapping of SAML attributes to user profile fields.e.g. {"email": "user.email", "firstName": "user.firstName"}

Response Fields

NameTypeRequiredDescription
idstringOptionalApplication ID.e.g. app_01hxyz
namestringOptionalApplication name.e.g. My Web App
typestringOptionalProtocol type.e.g. OIDC
clientIdstringOptionalGenerated OAuth 2.0 client ID.e.g. cid_abc123
clientSecretstringOptionalGenerated OAuth 2.0 client secret (shown once).e.g. cs_secret_value
organizationIdstringOptionalOwning organization ID.e.g. org_01hxyz
createdAtstringOptionalISO 8601 creation timestamp.e.g. 2025-01-15T10:30:00Z

Response Example

{
  "id": "app_01hxyz",
  "name": "My Web App",
  "description": "Customer-facing web application.",
  "type": "OIDC",
  "clientId": "cid_abc123",
  "clientSecret": "cs_secret_value",
  "redirectUris": [
    "https://app.example.com/callback"
  ],
  "grantTypes": [
    "authorization_code",
    "refresh_token"
  ],
  "responseTypes": [
    "code"
  ],
  "scopes": [
    "openid",
    "profile",
    "email"
  ],
  "tokenEndpointAuthMethod": "client_secret_post",
  "isPublicClient": false,
  "requireDpop": false,
  "dpopNonceEnabled": false,
  "isAiAgent": false,
  "organizationId": "org_01hxyz",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Code Examples

curl -X POST https://api.sutraid.com/api/v1/organizations/org_01hxyz/applications \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Web App",
    "description": "Customer-facing web application.",
    "type": "OIDC",
    "redirectUris": ["https://app.example.com/callback"],
    "grantTypes": ["authorization_code", "refresh_token"],
    "responseTypes": ["code"],
    "scopes": ["openid", "profile", "email"],
    "tokenEndpointAuthMethod": "client_secret_post",
    "isPublicClient": false
  }'
GET/api/v1/organizations/:orgId/applicationsList ApplicationsBearer Token▾

Retrieve all applications belonging to an organization.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hxyz

Response Fields

NameTypeRequiredDescription
idstringOptionalApplication ID.e.g. app_01hxyz
namestringOptionalApplication name.e.g. My Web App
typestringOptionalProtocol type.e.g. OIDC
clientIdstringOptionalOAuth 2.0 client ID.e.g. cid_abc123
organizationIdstringOptionalOwning organization ID.e.g. org_01hxyz
createdAtstringOptionalISO 8601 creation timestamp.e.g. 2025-01-15T10:30:00Z

Response Example

{
  "data": [
    {
      "id": "app_01hxyz",
      "name": "My Web App",
      "type": "OIDC",
      "clientId": "cid_abc123",
      "organizationId": "org_01hxyz",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "app_02abcd",
      "name": "Enterprise SAML App",
      "type": "SAML",
      "clientId": "cid_def456",
      "organizationId": "org_01hxyz",
      "createdAt": "2025-01-20T09:00:00Z",
      "updatedAt": "2025-01-20T09:00:00Z"
    }
  ]
}

Code Examples

curl -X GET https://api.sutraid.com/api/v1/organizations/org_01hxyz/applications \
  -H "Authorization: Bearer <token>"
GET/api/v1/organizations/:orgId/applications/:appIdGet ApplicationBearer Token▾

Retrieve a single application by its ID.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hxyz
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Response Fields

NameTypeRequiredDescription
idstringOptionalApplication ID.e.g. app_01hxyz
namestringOptionalApplication name.e.g. My Web App
typestringOptionalProtocol type.e.g. OIDC
clientIdstringOptionalOAuth 2.0 client ID.e.g. cid_abc123
redirectUrisstring[]OptionalAllowed redirect URIs.e.g. ["https://app.example.com/callback"]
grantTypesstring[]OptionalAllowed grant types.e.g. ["authorization_code"]
scopesstring[]OptionalAllowed scopes.e.g. ["openid", "profile", "email"]
organizationIdstringOptionalOwning organization ID.e.g. org_01hxyz
createdAtstringOptionalISO 8601 creation timestamp.e.g. 2025-01-15T10:30:00Z

Response Example

{
  "id": "app_01hxyz",
  "name": "My Web App",
  "description": "Customer-facing web application.",
  "type": "OIDC",
  "clientId": "cid_abc123",
  "redirectUris": [
    "https://app.example.com/callback"
  ],
  "grantTypes": [
    "authorization_code",
    "refresh_token"
  ],
  "responseTypes": [
    "code"
  ],
  "scopes": [
    "openid",
    "profile",
    "email"
  ],
  "tokenEndpointAuthMethod": "client_secret_post",
  "isPublicClient": false,
  "requireDpop": false,
  "dpopNonceEnabled": false,
  "isAiAgent": false,
  "organizationId": "org_01hxyz",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Code Examples

curl -X GET https://api.sutraid.com/api/v1/organizations/org_01hxyz/applications/app_01hxyz \
  -H "Authorization: Bearer <token>"
PUT/api/v1/organizations/:orgId/applications/:appIdUpdate ApplicationBearer Token▾

Update an existing application. All body fields mirror CreateApplicationDto and are optional (partial update).

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hxyz
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Request Body

NameTypeRequiredDescription
namestringOptionalUpdated display name (max 100 characters).e.g. My Updated App
descriptionstringOptionalUpdated description (max 500 characters).e.g. Updated description.
redirectUrisstring[]OptionalUpdated list of allowed redirect URIs.e.g. ["https://app.example.com/callback", "https://app.example.com/silent-renew"]
scopesstring[]OptionalUpdated list of allowed scopes.e.g. ["openid", "profile", "email", "phone"]

Response Fields

NameTypeRequiredDescription
idstringOptionalApplication ID.e.g. app_01hxyz
namestringOptionalUpdated application name.e.g. My Updated App
updatedAtstringOptionalISO 8601 update timestamp.e.g. 2025-02-01T12:00:00Z

Response Example

{
  "id": "app_01hxyz",
  "name": "My Updated App",
  "description": "Updated description.",
  "type": "OIDC",
  "clientId": "cid_abc123",
  "redirectUris": [
    "https://app.example.com/callback",
    "https://app.example.com/silent-renew"
  ],
  "grantTypes": [
    "authorization_code",
    "refresh_token"
  ],
  "responseTypes": [
    "code"
  ],
  "scopes": [
    "openid",
    "profile",
    "email",
    "phone"
  ],
  "tokenEndpointAuthMethod": "client_secret_post",
  "isPublicClient": false,
  "organizationId": "org_01hxyz",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-02-01T12:00:00Z"
}

Code Examples

curl -X PUT https://api.sutraid.com/api/v1/organizations/org_01hxyz/applications/app_01hxyz \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Updated App",
    "redirectUris": ["https://app.example.com/callback", "https://app.example.com/silent-renew"],
    "scopes": ["openid", "profile", "email", "phone"]
  }'
POST/api/v1/organizations/:orgId/applications/:appId/rotate-secretRotate Client SecretBearer Token▾

Generate a new client secret for an application, invalidating the previous one. Store the returned secret immediately — it will not be shown again.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hxyz
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Response Fields

NameTypeRequiredDescription
clientSecretstringOptionalNew client secret. Store this value securely — it will not be shown again.e.g. cs_new_secret_value

Response Example

{
  "clientSecret": "cs_new_secret_value"
}

Code Examples

curl -X POST https://api.sutraid.com/api/v1/organizations/org_01hxyz/applications/app_01hxyz/rotate-secret \
  -H "Authorization: Bearer <token>"
DELETE/api/v1/organizations/:orgId/applications/:appIdDelete ApplicationBearer Token▾

Permanently delete an application and all associated OAuth tokens and configurations.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hxyz
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Response Fields

NameTypeRequiredDescription
deletedbooleanOptionalWhether the application was successfully deleted.e.g. true
idstringOptionalID of the deleted application.e.g. app_01hxyz

Response Example

{
  "deleted": true,
  "id": "app_01hxyz"
}

Code Examples

curl -X DELETE https://api.sutraid.com/api/v1/organizations/org_01hxyz/applications/app_01hxyz \
  -H "Authorization: Bearer <token>"
PUT/api/v1/organizations/:orgId/applications/:appId/usersAssign Users to ApplicationBearer Token▾

Replace the full set of users assigned to an application. The provided list of userIds becomes the authoritative assignment.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hxyz
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Request Body

NameTypeRequiredDescription
userIdsstring[]RequiredArray of user IDs to assign to the application.e.g. ["user_abc", "user_def"]

Response Fields

NameTypeRequiredDescription
applicationIdstringOptionalApplication ID.e.g. app_01hxyz
userIdsstring[]OptionalUpdated list of assigned user IDs.e.g. ["user_abc", "user_def"]

Response Example

{
  "applicationId": "app_01hxyz",
  "userIds": [
    "user_abc",
    "user_def"
  ]
}

Code Examples

curl -X PUT https://api.sutraid.com/api/v1/organizations/org_01hxyz/applications/app_01hxyz/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"userIds": ["user_abc", "user_def"]}'
PUT/api/v1/organizations/:orgId/applications/:appId/groupsAssign Groups to ApplicationBearer Token▾

Replace the full set of groups assigned to an application. The provided list of groupIds becomes the authoritative assignment.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hxyz
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Request Body

NameTypeRequiredDescription
groupIdsstring[]RequiredArray of group IDs to assign to the application.e.g. ["grp_xyz", "grp_abc"]

Response Fields

NameTypeRequiredDescription
applicationIdstringOptionalApplication ID.e.g. app_01hxyz
groupIdsstring[]OptionalUpdated list of assigned group IDs.e.g. ["grp_xyz", "grp_abc"]

Response Example

{
  "applicationId": "app_01hxyz",
  "groupIds": [
    "grp_xyz",
    "grp_abc"
  ]
}

Code Examples

curl -X PUT https://api.sutraid.com/api/v1/organizations/org_01hxyz/applications/app_01hxyz/groups \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"groupIds": ["grp_xyz", "grp_abc"]}'
POST/api/v1/oauth/tokenToken ExchangeBasic Auth▾

Exchange an authorization code or refresh token for access tokens. Supports the authorization_code and refresh_token grant types. Client credentials can be sent either via HTTP Basic authentication or in the request body.

Parameters

NameTypeRequiredDescription
AuthorizationstringOptionalHTTP Basic credentials: Base64-encoded "client_id:client_secret".e.g. Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=

Request Body

NameTypeRequiredDescription
grant_typestringRequiredOAuth 2.0 grant type.e.g. authorization_code
authorization_coderefresh_token
codestringOptionalAuthorization code received from the authorization endpoint (required for authorization_code grant).e.g. SplxlOBeZQQYbYS6WxSbIA
refresh_tokenstringOptionalRefresh token (required for refresh_token grant).e.g. tGzv3JOkF0XG5Qx2TlKWIA
client_idstringOptionalClient ID (alternative to Basic auth).e.g. cid_abc123
client_secretstringOptionalClient secret (alternative to Basic auth).e.g. cs_secret_value
scopestringOptionalSpace-delimited list of requested scopes.e.g. openid profile email

Response Fields

NameTypeRequiredDescription
access_tokenstringOptionalJWT access token.e.g. eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
token_typestringOptionalToken type, always "Bearer".e.g. Bearer
expires_innumberOptionalToken lifetime in seconds.e.g. 3600
scopestringOptionalSpace-delimited list of granted scopes.e.g. openid profile email
refresh_tokenstringOptionalRefresh token (if refresh_token grant type was included).e.g. tGzv3JOkF0XG5Qx2TlKWIA

Response Example

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyX2FiYyJ9.signature",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email",
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

Code Examples

curl -X POST https://api.sutraid.com/api/v1/oauth/token \
  -H "Authorization: Basic $(echo -n 'cid_abc123:cs_secret_value' | base64)" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&scope=openid%20profile%20email"
POST/api/v1/oauth/introspectIntrospect Token▾

Determine whether a token is active and retrieve its metadata, as defined in RFC 7662.

Request Body

NameTypeRequiredDescription
tokenstringRequiredThe token to introspect (access token or refresh token).e.g. eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
client_idstringOptionalClient ID of the requesting application.e.g. cid_abc123

Response Fields

NameTypeRequiredDescription
activebooleanOptionalWhether the token is currently active.e.g. true
scopestringOptionalSpace-delimited list of scopes associated with the token.e.g. openid profile email
client_idstringOptionalClient ID the token was issued to.e.g. cid_abc123
expnumberOptionalUnix timestamp at which the token expires.e.g. 1736944200
substringOptionalSubject identifier (user ID).e.g. user_abc

Response Example

{
  "active": true,
  "scope": "openid profile email",
  "client_id": "cid_abc123",
  "exp": 1736944200,
  "sub": "user_abc",
  "iat": 1736940600
}

Code Examples

curl -X POST https://api.sutraid.com/api/v1/oauth/introspect \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "client_id": "cid_abc123"
  }'
POST/api/v1/oauth/revokeRevoke Token▾

Immediately revoke an access token or refresh token, as defined in RFC 7009. Revoked tokens are rejected by the introspection endpoint.

Request Body

NameTypeRequiredDescription
tokenstringRequiredThe token to revoke.e.g. eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Response Fields

NameTypeRequiredDescription
statusstringOptionalRevocation status.e.g. revoked

Response Example

{
  "status": "revoked"
}

Code Examples

curl -X POST https://api.sutraid.com/api/v1/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}'
POST/api/v1/oauth/registerDynamic Client Registration▾

Register a new OAuth 2.0 client dynamically, as per RFC 7591. Requires an x-api-token header for authorization. Returns client credentials and a registration access token for subsequent management.

Parameters

NameTypeRequiredDescription
x-api-tokenstringRequiredAPI token used to authorize dynamic client registration.e.g. apitok_xyz789

Request Body

NameTypeRequiredDescription
client_namestringRequiredHuman-readable name for the client.e.g. My AI Agent
organization_idstringRequiredOrganization ID the client will be registered under.e.g. org_01hxyz
scopestringOptionalSpace-delimited list of requested scopes.e.g. openid profile email
jwksobjectOptionalJSON Web Key Set for the client (used for private_key_jwt auth).e.g. {"keys": [...]}

Response Fields

NameTypeRequiredDescription
client_idstringOptionalGenerated client ID.e.g. cid_dynamic_abc
client_secretstringOptionalGenerated client secret.e.g. cs_dynamic_secret
registration_access_tokenstringOptionalToken used to manage this client registration.e.g. rat_xyz
registration_client_uristringOptionalURI for managing this client registration.e.g. https://api.sutraid.com/api/v1/oauth/register/cid_dynamic_abc

Response Example

{
  "client_id": "cid_dynamic_abc",
  "client_secret": "cs_dynamic_secret",
  "registration_access_token": "rat_xyz789",
  "registration_client_uri": "https://api.sutraid.com/api/v1/oauth/register/cid_dynamic_abc"
}

Code Examples

curl -X POST https://api.sutraid.com/api/v1/oauth/register \
  -H "x-api-token: apitok_xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My AI Agent",
    "organization_id": "org_01hxyz",
    "scope": "openid profile email"
  }'
GET/api/v1/.well-known/openid-configuration/:orgIdOIDC Discovery▾

Retrieve the OpenID Connect discovery document for an organization. Clients use this endpoint to auto-configure OIDC parameters such as the issuer, authorization endpoint, token endpoint, and supported algorithms.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hxyz

Response Fields

NameTypeRequiredDescription
issuerstringOptionalToken issuer identifier.e.g. https://api.sutraid.com/org_01hxyz
authorization_endpointstringOptionalAuthorization endpoint URL.e.g. https://api.sutraid.com/api/v1/oauth/authorize
token_endpointstringOptionalToken endpoint URL.e.g. https://api.sutraid.com/api/v1/oauth/token
userinfo_endpointstringOptionalUserInfo endpoint URL.e.g. https://api.sutraid.com/api/v1/oauth/userinfo
jwks_uristringOptionalJSON Web Key Set endpoint URL.e.g. https://api.sutraid.com/api/v1/.well-known/jwks.json
scopes_supportedstring[]OptionalList of supported scopes.e.g. ["openid", "profile", "email", "phone", "address"]
response_types_supportedstring[]OptionalSupported response types.e.g. ["code"]
grant_types_supportedstring[]OptionalSupported grant types.e.g. ["authorization_code", "refresh_token"]
id_token_signing_alg_values_supportedstring[]OptionalSupported ID token signing algorithms.e.g. ["RS256"]

Response Example

{
  "issuer": "https://api.sutraid.com/org_01hxyz",
  "authorization_endpoint": "https://api.sutraid.com/api/v1/oauth/authorize",
  "token_endpoint": "https://api.sutraid.com/api/v1/oauth/token",
  "userinfo_endpoint": "https://api.sutraid.com/api/v1/oauth/userinfo",
  "jwks_uri": "https://api.sutraid.com/api/v1/.well-known/jwks.json",
  "registration_endpoint": "https://api.sutraid.com/api/v1/oauth/register",
  "scopes_supported": [
    "openid",
    "profile",
    "email",
    "phone",
    "address"
  ],
  "response_types_supported": [
    "code"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "private_key_jwt"
  ],
  "claims_supported": [
    "sub",
    "iss",
    "aud",
    "exp",
    "iat",
    "email",
    "name",
    "given_name",
    "family_name"
  ]
}

Code Examples

curl -X GET https://api.sutraid.com/api/v1/.well-known/openid-configuration/org_01hxyz
GET/api/v1/saml/:orgId/:appId/metadata.xmlGet SAML IdP Metadata▾

Retrieve the SAML Identity Provider metadata XML for a specific application. Provide this to your Service Provider to configure the SAML trust relationship.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hxyz
appIdstringRequiredThe unique identifier of the SAML application.e.g. app_saml_01

Response Fields

NameTypeRequiredDescription
EntityDescriptorXML elementOptionalRoot SAML metadata element containing the IdP descriptor.
IDPSSODescriptorXML elementOptionalIdP SSO descriptor with signing certificate and SSO endpoints.
SingleSignOnServiceXML elementOptionalSSO endpoint location and binding.

Response Example

{
  "contentType": "application/xml",
  "body": "<?xml version=\"1.0\"?><EntityDescriptor entityID=\"https://api.sutraid.com/saml/org_01hxyz/app_saml_01\">...</EntityDescriptor>"
}

Code Examples

curl -X GET https://api.sutraid.com/api/v1/saml/org_01hxyz/app_saml_01/metadata.xml \
  -H "Accept: application/xml"
POST/api/v1/saml/:orgId/:appId/ssoSAML SSO Endpoint▾

SAML Single Sign-On endpoint. Receives a SAMLRequest from the Service Provider, validates it, authenticates the user, and returns an HTML page with an auto-submitting form containing the signed SAMLResponse destined for the SP Assertion Consumer Service URL.

Parameters

NameTypeRequiredDescription
orgIdstringRequiredThe unique identifier of the organization.e.g. org_01hxyz
appIdstringRequiredThe unique identifier of the SAML application.e.g. app_saml_01

Request Body

NameTypeRequiredDescription
SAMLRequeststringOptionalBase64-encoded, deflate-compressed SAML AuthnRequest from the Service Provider.e.g. PHNhbWxwOkF1dGhuUmVxdWVzdC4uLj4=
RelayStatestringOptionalOpaque value that will be returned to the SP with the SAMLResponse.e.g. https://app.example.com/dashboard

Response Fields

NameTypeRequiredDescription
HTMLstringOptionalHTML page containing an auto-submitting form that POSTs the SAMLResponse to the SP ACS URL.
SAMLResponsestringOptionalBase64-encoded signed SAML assertion, embedded in the form.
RelayStatestringOptionalOriginal RelayState value, echoed back to the SP.

Response Example

{
  "contentType": "text/html",
  "body": "<html><body><form method=\"POST\" action=\"https://app.example.com/saml/acs\"><input type=\"hidden\" name=\"SAMLResponse\" value=\"PHNhbWxwOlJlc3BvbnNlLi4uPg==\" /><input type=\"hidden\" name=\"RelayState\" value=\"https://app.example.com/dashboard\" /><noscript><button type=\"submit\">Continue</button></noscript></form><script>document.forms[0].submit();</script></body></html>"
}

Code Examples

curl -X POST https://api.sutraid.com/api/v1/saml/org_01hxyz/app_saml_01/sso \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "SAMLRequest=PHNhbWxwOkF1dGhuUmVxdWVzdC4uLj4%3D&RelayState=https%3A%2F%2Fapp.example.com%2Fdashboard"