Get SAML SP Metadata

GET

auth

saml

{tenantID}

metadata

SP metadata XML for a tenant

curl --request GET \
  --url https://billing.example.com/auth/saml/{tenantID}/metadata \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://billing.example.com/auth/saml/{tenantID}/metadata', 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}/metadata",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

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

"<string>"

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

Returns the Service Provider (SP) metadata document for a tenant, as application/samlmetadata+xml. Hand this document to the tenant’s identity provider when configuring the connection: it carries the SP entity id, the Assertion Consumer Service URLs (POST /auth/saml/{tenantID}/acs), the SP certificate (published for encryption use), and the SP’s requirements: WantAssertionsSigned="true" and AuthnRequestsSigned="false" — Recurso does not sign its AuthnRequests, so the document carries no signing key. The endpoint is public and unauthenticated so an IdP can fetch it directly, but it only answers for tenants that have an SSO connection row. The row does not need to be enabled or fully configured yet — you can hand the metadata to the IdP before the IdP details are stored — but users cannot start an SP-initiated login with GET /auth/saml/{tenantID}/login until the connection is both configured and enabled.

Path Parameters

Parameter	Type	Required	Description
`tenantID`	string (uuid)	Yes	The tenant whose SP metadata to return.

Example Request

curl https://api.recurso.dev/auth/saml/d4c3b2a1-0f9e-4765-8321-abcdef012345/metadata

Example Response

The body is XML, not JSON:

<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
  validUntil="2026-09-06T10:15:00Z"
  entityID="https://api.recurso.dev/auth/saml/d4c3b2a1-0f9e-4765-8321-abcdef012345/metadata">
  <SPSSODescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
    validUntil="2026-09-06T10:15:00Z"
    protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"
    AuthnRequestsSigned="false" WantAssertionsSigned="true">
    <KeyDescriptor use="encryption">
      <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
        <X509Data xmlns="http://www.w3.org/2000/09/xmldsig#">
          <X509Certificate xmlns="http://www.w3.org/2000/09/xmldsig#">MIIC5TCCAc2gAwIBAgIQ...</X509Certificate>
        </X509Data>
      </KeyInfo>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"></EncryptionMethod>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes192-cbc"></EncryptionMethod>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"></EncryptionMethod>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"></EncryptionMethod>
    </KeyDescriptor>
    <NameIDFormat></NameIDFormat>
    <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://api.recurso.dev/auth/saml/d4c3b2a1-0f9e-4765-8321-abcdef012345/acs" index="1"></AssertionConsumerService>
    <AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact" Location="https://api.recurso.dev/auth/saml/d4c3b2a1-0f9e-4765-8321-abcdef012345/acs" index="2"></AssertionConsumerService>
  </SPSSODescriptor>
</EntityDescriptor>

The validUntil attributes are set 48 hours from the time of the request, so an IdP that caches metadata should re-fetch it periodically. The NameIDFormat element is present but empty — the SP does not require a particular NameID format; it reads the user’s email from the assertion. Only the HTTP-POST ACS (index 1) is used by Recurso’s login flow; the HTTP-Artifact entry is emitted by the SAML library and is not backed by an artifact resolution step.

Errors

Status	Code	When	Fix
`404`	`not_found`	`tenantID` is not a valid UUID, or the tenant has no SSO connection row at all.	Create the tenant’s SAML connection in the dashboard first (it does not need to be enabled yet), then fetch the metadata.

Errors use the standard envelope — see Errors.

Authorizations

Authorization

string

header

required

Path Parameters

tenantID

string<uuid>

required

Response

SP metadata XML.

The response is of type string.

SP metadata XML for a tenant

curl --request GET \
  --url https://billing.example.com/auth/saml/{tenantID}/metadata \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://billing.example.com/auth/saml/{tenantID}/metadata', 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}/metadata",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

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

"<string>"

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

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Path Parameters

Example Request

Example Response

Errors

Authorizations

Path Parameters

Response

​Path Parameters

​Example Request

​Example Response

​Errors

Authorizations

Path Parameters

Response

Path Parameters

Example Request

Example Response

Errors