> ## Documentation Index > Fetch the complete documentation index at: https://docs.recurso.dev/llms.txt > Use this file to discover all available pages before exploring further. # Get SSO Connection > Return the caller tenant's SAML SSO connection, including the public SP URLs to hand to the identity provider. Returns the tenant's SAML SSO connection: the identity provider (IdP) details an admin submitted with [`PUT /v1/sso/connection`](/api-reference/sso/update), whether the connection is enabled, and the two public Service Provider (SP) URLs the IdP needs — the [SP metadata](/api-reference/auth/saml-metadata) URL and the [Assertion Consumer Service](/api-reference/auth/saml-acs) 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`](/api-reference/sso/delete). ## Example Request ```bash theme={null} 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 ```json theme={null} { "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 ` 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`](/api-reference/sso/update). | | `500` | `internal_error` | The connection could not be read. | Retry; if it persists, contact support. | Errors use the standard envelope — see [Errors](/api-reference/errors). ## OpenAPI ````yaml GET /v1/sso/connection openapi: 3.1.0 info: title: Recurso API version: 1.0.0 description: | The Recurso billing engine REST API. Authenticate by passing your API key as a bearer token: Authorization: Bearer Obtain an API key by registering a tenant via `POST /auth/register`. All authenticated endpoints live under the `/v1` prefix. Mutating endpoints support idempotency via the `Idempotency-Key` header. license: name: MIT identifier: MIT servers: - url: https://billing.example.com description: >- Example deployment — substitute the base URL of your own Recurso deployment. security: - bearerAuth: [] tags: - name: System description: Health, version, and API metadata - name: Auth description: Tenant registration - name: Plans description: Product catalog plans - name: Customers description: Customer management - name: Subscriptions description: Subscription lifecycle - name: Invoices description: Invoices, PDFs, and Indian GST e-invoicing - name: Coupons description: Discounts - name: Usage description: Metered usage events - name: Credit Notes description: Customer credits - name: Quotes description: Quote-to-invoice lifecycle - name: Webhooks description: Webhook endpoint management and event feed - name: Analytics description: Revenue analytics - name: Checkout description: Public hosted checkout for invoices - name: Payments description: Payment order creation - name: Inbound Webhooks description: Receivers for payment-gateway callbacks (Razorpay, Stripe) - name: Customer Portal description: Customer-facing portal — magic-link auth and session-scoped data - name: Developer description: API key management - name: Account description: Tenant account settings - name: Finance description: Ledger accounts, entries, reconciliation, and revenue recognition - name: Settings description: Tax (GST) and e-invoicing (IRP) configuration - name: Consents description: Consent records for RBI-compliant recurring billing - name: Referrals description: Customer referral program - name: Gifts description: Gift subscriptions - name: Mandates description: UPI Autopay mandates - name: Offline Payments description: Virtual accounts and manually recorded payments - name: Organizations description: Multi-entity organizations grouping several tenants - name: Accounting description: QuickBooks / Xero accounting integrations - name: Churn description: Churn risk scoring and alerts - name: Cancel Flows description: Configurable retention flows shown at cancellation time - name: Dunning description: Dunning analytics and multi-channel dunning campaigns paths: /v1/sso/connection: get: tags: - Auth summary: Get the caller tenant's SAML SSO connection operationId: getSSOConnection responses: '200': description: The tenant's SSO connection. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SSOConnection' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' security: - sessionCookie: [] - bearerAuth: [] components: schemas: SSOConnection: type: object properties: tenant_id: type: string format: uuid idp_entity_id: type: string idp_sso_url: type: string idp_certificate: type: string description: Base64/PEM X.509 signing certificate. idp_metadata_xml: type: string description: >- Optional full IdP metadata; takes precedence over the discrete fields. enabled: type: boolean configured: type: boolean description: Whether the connection has enough IdP detail to attempt a login. sp_metadata_url: type: string description: Public SP metadata URL to hand to the IdP. sp_acs_url: type: string description: Public SP Assertion Consumer Service URL. required: - tenant_id - enabled - configured Error: type: object required: - error properties: error: type: object description: Structured error detail. required: - code - message properties: code: type: string description: Stable machine-readable error code. examples: - validation_failed - unauthorized - forbidden - not_found - conflict - rate_limited - internal_error - invalid_api_key - key_mode_mismatch - over_refund - invoice_not_paid - invoice_already_paid message: type: string description: Human-readable explanation. responses: Unauthorized: description: Missing or invalid credentials (API key or session cookie). content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`. sessionCookie: type: apiKey in: cookie name: recurso_session description: > 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`). ````