Get SSO Connection

GET

sso

connection

Get the caller tenant's SAML SSO connection

curl --request GET \
  --url https://billing.example.com/v1/sso/connection \
  --cookie recurso_session=

const options = {method: 'GET', headers: {cookie: 'recurso_session='}};

fetch('https://billing.example.com/v1/sso/connection', 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/v1/sso/connection",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_COOKIE => "recurso_session=",
]);

$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/v1/sso/connection"

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

	req.Header.Add("cookie", "recurso_session=")

	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/v1/sso/connection")

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

request = Net::HTTP::Get.new(url)
request["cookie"] = 'recurso_session='

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

{
  "data": {
    "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "enabled": true,
    "configured": true,
    "idp_entity_id": "<string>",
    "idp_sso_url": "<string>",
    "idp_certificate": "<string>",
    "idp_metadata_xml": "<string>",
    "sp_metadata_url": "<string>",
    "sp_acs_url": "<string>"
  }
}

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

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

Returns the tenant’s SAML SSO connection: the identity provider (IdP) details an admin submitted with PUT /v1/sso/connection, whether the connection is enabled, and the two public Service Provider (SP) URLs the IdP needs — the SP metadata URL and the Assertion Consumer Service URL. Each tenant has at most one connection, so there is no ID to pass. Any authenticated member of the tenant can read the connection; only owners and admins can change it. The IdP certificate and metadata XML are returned as stored — what the admin submitted, with surrounding whitespace trimmed — and nothing beyond what the admin entered is exposed. Remove the connection with DELETE /v1/sso/connection.

Example Request

curl https://api.recurso.dev/v1/sso/connection \
  -H "Authorization: Bearer $API_KEY"

Dashboard sessions authenticate with the recurso_session cookie instead of a bearer token.

Response

{
  "data": {
    "tenant_id": "d4c3b2a1-0f9e-4765-8321-abcdef012345",
    "idp_entity_id": "http://www.okta.com/exk1a2b3c4d5e6f7g8h9",
    "idp_sso_url": "https://acme.okta.com/app/acme_recurso_1/exk1a2b3c4d5e6f7g8h9/sso/saml",
    "idp_certificate": "-----BEGIN CERTIFICATE-----\nMIIDpDCCAoygAwIBAgIGAYt...\n-----END CERTIFICATE-----",
    "idp_metadata_xml": "",
    "enabled": true,
    "configured": true,
    "sp_metadata_url": "https://api.recurso.dev/auth/saml/d4c3b2a1-0f9e-4765-8321-abcdef012345/metadata",
    "sp_acs_url": "https://api.recurso.dev/auth/saml/d4c3b2a1-0f9e-4765-8321-abcdef012345/acs"
  }
}

Fields

Field	Type	Description
`tenant_id`	string (uuid)	The tenant that owns the connection. Also the `{tenantID}` segment of the public SP endpoints.
`idp_entity_id`	string	The IdP’s SAML entity id (issuer). Empty when only `idp_metadata_xml` was submitted; every submitted field is stored as sent (trimmed), so a connection given both keeps both.
`idp_sso_url`	string	The IdP’s HTTP-Redirect SingleSignOnService location that logins redirect to.
`idp_certificate`	string	The IdP’s base64/PEM X.509 signing certificate used to validate assertions.
`idp_metadata_xml`	string	The IdP’s full metadata document, or empty when only the discrete fields were submitted. When both are present, the metadata XML takes precedence.
`enabled`	boolean	Whether the public SP login and ACS endpoints answer for this tenant.
`configured`	boolean	Whether the connection holds enough IdP detail to attempt a login: either `idp_metadata_xml`, or all of `idp_entity_id`, `idp_sso_url` and `idp_certificate`.
`sp_metadata_url`	string	Public URL of the tenant’s SP metadata document. Give this to the IdP.
`sp_acs_url`	string	Public URL the IdP posts the `SAMLResponse` to.

Errors

Status	Code	When	Fix
`401`	`unauthorized`	No API key or session cookie was sent. An invalid API key returns `invalid_api_key`; a key for the wrong mode (live vs test) returns `key_mode_mismatch`.	Send `Authorization: Bearer <api_key>` with a key for the right mode, or sign in to the dashboard.
`404`	`not_found`	The tenant has no SSO connection configured yet.	Create one with `PUT /v1/sso/connection`.
`500`	`internal_error`	The connection could not be read.	Retry; if it persists, contact support.

Errors use the standard envelope — see Errors.

Authorizations

recurso_session

string

required

Dashboard user session cookie (httpOnly) issued by POST /auth/register and POST /auth/login. v1 endpoints accept EITHER this cookie or the tenant API key (bearerAuth).

Response

The tenant's SSO connection.

data

object

Show child attributes

Get the caller tenant's SAML SSO connection

curl --request GET \
  --url https://billing.example.com/v1/sso/connection \
  --cookie recurso_session=

const options = {method: 'GET', headers: {cookie: 'recurso_session='}};

fetch('https://billing.example.com/v1/sso/connection', 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/v1/sso/connection",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_COOKIE => "recurso_session=",
]);

$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/v1/sso/connection"

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

	req.Header.Add("cookie", "recurso_session=")

	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/v1/sso/connection")

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

request = Net::HTTP::Get.new(url)
request["cookie"] = 'recurso_session='

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

{
  "data": {
    "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "enabled": true,
    "configured": true,
    "idp_entity_id": "<string>",
    "idp_sso_url": "<string>",
    "idp_certificate": "<string>",
    "idp_metadata_xml": "<string>",
    "sp_metadata_url": "<string>",
    "sp_acs_url": "<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

Example Request

Response

Fields

Errors

Authorizations

Response

​Example Request

​Response

​Fields

​Errors

Authorizations

Response

Example Request

Response

Fields

Errors