SAML ACS
Contents
Mobile_API »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 (
30requests 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) |
