Consume a SAML Assertion

POST

auth

saml

{tenantID}

acs

Assertion Consumer Service (IdP posts the SAMLResponse here)

curl --request POST \
  --url https://billing.example.com/auth/saml/{tenantID}/acs \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'SAMLResponse=<string>' \
  --data 'RelayState=<string>'

import requests

url = "https://billing.example.com/auth/saml/{tenantID}/acs"

payload = {
    "SAMLResponse": "<string>",
    "RelayState": "<string>"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/x-www-form-urlencoded"
}

response = requests.post(url, data=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: '<api-key>',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({SAMLResponse: '<string>', RelayState: '<string>'})
};

fetch('https://billing.example.com/auth/saml/{tenantID}/acs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/auth/saml/{tenantID}/acs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "SAMLResponse=%3Cstring%3E&RelayState=%3Cstring%3E",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/x-www-form-urlencoded"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/auth/saml/{tenantID}/acs"

	payload := strings.NewReader("SAMLResponse=%3Cstring%3E&RelayState=%3Cstring%3E")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://billing.example.com/auth/saml/{tenantID}/acs")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/x-www-form-urlencoded")
  .body("SAMLResponse=%3Cstring%3E&RelayState=%3Cstring%3E")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/auth/saml/{tenantID}/acs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/x-www-form-urlencoded'
request.body = "SAMLResponse=%3Cstring%3E&RelayState=%3Cstring%3E"

response = http.request(request)
puts response.read_body

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

The Assertion Consumer Service (ACS). After the user authenticates at the identity provider — typically following GET /auth/saml/{tenantID}/login — the IdP posts a form-encoded SAMLResponse to this URL. The server validates the signature against the tenant’s stored IdP certificate, extracts the email, and maps it to an existing user in the tenant. There is no just-in-time provisioning: an email that no tenant user owns is rejected, so invite the user first. On success the server sets the recurso_session cookie — the same session a password login issues — and 302s to the dashboard root. The IdP submits this request from the user’s browser; you do not call it yourself. Its URL is published in the SP metadata.

Path Parameters

Parameter	Type	Required	Description
`tenantID`	string (uuid)	Yes	The tenant the assertion belongs to. Its SSO connection must exist and be enabled.

Body Parameters

The body is application/x-www-form-urlencoded, as sent by the HTTP-POST binding.

Parameter	Type	Required	Description
`SAMLResponse`	string	Yes	The base64-encoded SAML response from the IdP, signed with the certificate stored on the tenant’s connection.
`RelayState`	string	No	Part of the HTTP-POST binding, accepted for compatibility. Recurso’s `AuthnRequest` sets no relay state and this endpoint ignores the field: the post-login redirect is always the dashboard root.

Example Request

curl -i -X POST https://api.recurso.dev/auth/saml/d4c3b2a1-0f9e-4765-8321-abcdef012345/acs \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "SAMLResponse=PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46b2FzaXM6..."

Example Response

There is no response body. A successful login answers 302 Found with the session cookie:

HTTP/1.1 302 Found
Location: https://app.recurso.dev/
Set-Cookie: recurso_session=...; Path=/; HttpOnly; Secure; SameSite=Lax

Errors

Status	Code	When	Fix
`401`	`unauthorized`	The `SAMLResponse` failed validation — bad signature, wrong audience, expired, or replayed.	Confirm the IdP certificate on the tenant’s connection matches the IdP’s current signing certificate and that the IdP targets this tenant’s ACS URL.
`403`	`forbidden`	The assertion is valid but no user in the tenant has the asserted email.	Have a tenant admin invite the user with that email, then retry the login.
`404`	`not_found`	`tenantID` is not a valid UUID, or the tenant’s SSO connection is missing or disabled.	Enable the tenant’s SAML connection in the dashboard.
`500`	`internal_error`	The assertion could not be processed or the session could not be opened.	Retry; if it persists, contact support.

Errors use the standard envelope — see Errors.

Authorizations

Authorization

string

header

required

Path Parameters

tenantID

string<uuid>

required

Body

application/x-www-form-urlencoded

SAMLResponse

string

RelayState

string

Response

Redirect to the dashboard on success. Sets the session cookie.

Assertion Consumer Service (IdP posts the SAMLResponse here)

curl --request POST \
  --url https://billing.example.com/auth/saml/{tenantID}/acs \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'SAMLResponse=<string>' \
  --data 'RelayState=<string>'

import requests

url = "https://billing.example.com/auth/saml/{tenantID}/acs"

payload = {
    "SAMLResponse": "<string>",
    "RelayState": "<string>"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/x-www-form-urlencoded"
}

response = requests.post(url, data=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: '<api-key>',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({SAMLResponse: '<string>', RelayState: '<string>'})
};

fetch('https://billing.example.com/auth/saml/{tenantID}/acs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/auth/saml/{tenantID}/acs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "SAMLResponse=%3Cstring%3E&RelayState=%3Cstring%3E",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/x-www-form-urlencoded"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/auth/saml/{tenantID}/acs"

	payload := strings.NewReader("SAMLResponse=%3Cstring%3E&RelayState=%3Cstring%3E")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://billing.example.com/auth/saml/{tenantID}/acs")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/x-www-form-urlencoded")
  .body("SAMLResponse=%3Cstring%3E&RelayState=%3Cstring%3E")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/auth/saml/{tenantID}/acs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/x-www-form-urlencoded'
request.body = "SAMLResponse=%3Cstring%3E&RelayState=%3Cstring%3E"

response = http.request(request)
puts response.read_body

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Consume a SAML Assertion

Path Parameters

Body Parameters

Example Request

Example Response

Errors

Authorizations

Path Parameters

Body

Response

​Path Parameters

​Body Parameters

​Example Request

​Example Response

​Errors

Authorizations

Path Parameters

Body

Response

Path Parameters

Body Parameters

Example Request

Example Response

Errors