> ## 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. # Consume a SAML Assertion > Assertion Consumer Service: the identity provider posts the SAMLResponse here to open a dashboard session. The Assertion Consumer Service (ACS). After the user authenticates at the identity provider — typically following [`GET /auth/saml/{tenantID}/login`](/api-reference/auth/saml-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](/api-reference/auth/login) issues — and `302`s 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](/api-reference/auth/saml-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 ```bash theme={null} 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 theme={null} 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](/api-reference/errors). ## OpenAPI ````yaml POST /auth/saml/{tenantID}/acs 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: /auth/saml/{tenantID}/acs: post: tags: - Auth summary: Assertion Consumer Service (IdP posts the SAMLResponse here) description: > Validates the SAMLResponse against the tenant's IdP certificate, extracts the email, and maps it to an EXISTING user in the tenant (no JIT provisioning). On success sets the `recurso_session` cookie and 302s to the dashboard. Unknown email → 403; disabled/unconfigured tenant → 404; invalid assertion → 401. operationId: samlACS parameters: - name: tenantID in: path required: true schema: type: string format: uuid requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: SAMLResponse: type: string RelayState: type: string responses: '302': description: Redirect to the dashboard on success. Sets the session cookie. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' security: [] components: responses: Unauthorized: description: Missing or invalid credentials (API key or session cookie). content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Authenticated but not permitted (insufficient role). content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' schemas: 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. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`. ````