Ashley DeBon: /* SAML Assertion Consumer Service (ACS) */

2026-07-24T07:16:33Z

‎SAML Assertion Consumer Service (ACS)

Ashley DeBon: Created page with "== SAML Assertion Consumer Service (ACS) == === Base URL === https://apimobile.callproof.com === Endpoint === /api/saml/acs === Purpose === Receives the Identity Provider (..."

2026-07-24T07:16:20Z

Created page with "== SAML Assertion Consumer Service (ACS) == === Base URL === https://apimobile.callproof.com === Endpoint === /api/saml/acs === Purpose === Receives the Identity Provider (..."

New page

== SAML Assertion Consumer Service (ACS) ==

=== Base URL ===
https://apimobile.callproof.com

=== Endpoint ===
/api/saml/acs

=== Purpose ===
Receives the Identity Provider (IdP) SAML authentication response after SSO login. Validates the assertion, resolves or provisions the CallProof user, issues a short-lived authorization code, and redirects the mobile app back with either a success code or an error.

This endpoint is called by the IdP (browser POST), not typically by the mobile app directly. Rate limited to 30 requests per minute.

=== HTTP Method ===
POST

=== Headers ===
{| class="wikitable"
! Header !! Required !! Description
|-
| Content-Type || Yes || <code>application/x-www-form-urlencoded</code> (standard SAML HTTP-POST binding)
|}

=== Security ===
* '''No Bearer token required''' – This is a public SSO callback endpoint (outside authenticated API middleware).
* Protected by request throttling (<code>30</code> requests per minute).
* SAML response signature/assertion validation is enforced by the SSO service configuration.

=== Parameters ===

==== Path Parameters ====
None.

==== Query Parameters ====
None.

==== Request Body ====
{| class="wikitable"
! Parameter !! Type !! Required !! Description
|-
| SAMLResponse || string || Yes || Base64-encoded SAML authentication response from the IdP
|-
| RelayState || string || No || Mobile redirect / callback target used to return the user to the app after SSO. If omitted or invalid, the configured default mobile redirect is used
|}

=== Successful Response (302 Redirect) ===
On success, the API does '''not''' return JSON. It redirects the mobile app callback URL with an authorization code.

{| class="wikitable"
! Field !! Type !! Description
|-
| HTTP status || integer || Redirect (typically 302)
|-
| Location || string || Mobile callback URL with query parameter <code>code</code> (authorization code to exchange for an access token via the SAML login endpoint)
|}

Example callback shape: mobile redirect URL with <code>?code={authorization_code}</code>

=== Error Responses ===
Errors are also returned as redirects to the mobile callback URL (not typical JSON API error bodies), with query parameters:

{| class="wikitable"
! Query Parameter !! Description
|-
| error || Error key (for example, "Authentication failed" or "User not found")
|-
| message || Human-readable error detail
|}

Common error cases:

* Missing <code>SAMLResponse</code> — message: "SAMLResponse parameter is missing from the request"
* Expired/invalid SSO session (RelayState/authn request) — message: "SSO session expired or invalid. Please try again."
* Invalid SAML assertion — message: "SSO authentication failed. Please try again."
* No email/user identifier in SAML response — message: "SSO login failed: no valid email address in SAML response."
* User not found in CallProof — error: "User not found", message: "User not found in CallProof"
* Authorization code could not be issued — message: "SSO authentication failed. Please try again."

{| class="wikitable"
! Status Code !! Meaning
|-
| 302 || Redirect to mobile app with <code>code</code> (success) or <code>error</code>/<code>message</code> (failure)
|-
| 429 || Too Many Requests – throttle limit exceeded (30 requests/minute)
|}

← Older revision		Revision as of 07:16, 24 July 2026
Line 1:		Line 1:
−	== SAML Assertion Consumer Service (ACS) ==	+	== [[Mobile_API]] »SAML Assertion Consumer Service (ACS) ==

	=== Base URL ===		=== Base URL ===

SAML ACS - Revision history

Ashley DeBon: /* SAML Assertion Consumer Service (ACS) */

Ashley DeBon: Created page with "== SAML Assertion Consumer Service (ACS) == === Base URL === https://apimobile.callproof.com === Endpoint === /api/saml/acs === Purpose === Receives the Identity Provider (..."