SAML ACS

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

Header	Required	Description
Content-Type	Yes	application/x-www-form-urlencoded (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 (30 requests per minute).
• SAML response signature/assertion validation is enforced by the SSO service configuration.

Parameters

Path Parameters

None.

Query Parameters

None.

Request Body

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.

Field	Type	Description
HTTP status	integer	Redirect (typically 302)
Location	string	Mobile callback URL with query parameter code (authorization code to exchange for an access token via the SAML login endpoint)

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

Error Responses

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

Query Parameter	Description
error	Error key (for example, "Authentication failed" or "User not found")
message	Human-readable error detail

Common error cases:

• Missing SAMLResponse — 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."

Status Code	Meaning
302	Redirect to mobile app with code (success) or error/message (failure)
429	Too Many Requests – throttle limit exceeded (30 requests/minute)