> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Auth API

> Auth endpoints exposed by the Devotel CPaaS API

# Auth API

Auth endpoints exposed by the Devotel CPaaS API

**Base path:** `/auth/saml`

**Endpoint count:** 4

***

### Start SAML SSO login

<Note>
  `GET /auth/saml/{orgSlug}/login`
</Note>

Service-provider-initiated SAML 2.0 login. Generates a SAML AuthnRequest for the organization's configured identity provider and 302-redirects the browser to the IdP's SSO URL. Pass an optional `redirect` target that is signed into the RelayState and honoured after the IdP returns to the callback endpoint. Unauthenticated — this begins the session rather than requiring one.

<ParamField path="orgSlug" type="string" required>
  URL-safe organization slug that selects the SAML configuration.
</ParamField>

<ParamField query="redirect" type="string">
  Optional post-authentication destination, echoed back via RelayState after the IdP round-trip.
</ParamField>

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl "https://api.orbit.devotel.io/auth/saml/{orgSlug}/login" \
      -H "X-API-Key: dv_live_sk_your_key_here"
    ```

    ```typescript Node.js theme={null}
    const res = await fetch('https://api.orbit.devotel.io/auth/saml/{orgSlug}/login', {
      method: 'GET',
      headers: {
        'X-API-Key': process.env.ORBIT_API_KEY!
      }
    });
    const data = await res.json();
    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    r = requests.get("https://api.orbit.devotel.io/auth/saml/{orgSlug}/login", headers=headers)
    print(r.json())
    ```
  </CodeGroup>
</RequestExample>

***

### Start SAML single logout

<Note>
  `GET /auth/saml/{orgSlug}/logout`
</Note>

Service-provider-initiated SAML 2.0 Single Logout (SLO). Builds a LogoutRequest for the organization's identity provider and 302-redirects the browser to the IdP's SLO endpoint; the local Clerk session is destroyed separately by the front-end once the IdP returns. Pass the optional `nameId` of the subject to log out. When no SLO endpoint is configured the endpoint responds `200` with a `logged_out` status instead of redirecting.

<ParamField path="orgSlug" type="string" required>
  URL-safe organization slug that selects the SAML configuration.
</ParamField>

<ParamField query="nameId" type="string">
  The SAML NameID of the subject being logged out, included in the LogoutRequest when supplied.
</ParamField>

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl "https://api.orbit.devotel.io/auth/saml/{orgSlug}/logout" \
      -H "X-API-Key: dv_live_sk_your_key_here"
    ```

    ```typescript Node.js theme={null}
    const res = await fetch('https://api.orbit.devotel.io/auth/saml/{orgSlug}/logout', {
      method: 'GET',
      headers: {
        'X-API-Key': process.env.ORBIT_API_KEY!
      }
    });
    const data = await res.json();
    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    r = requests.get("https://api.orbit.devotel.io/auth/saml/{orgSlug}/logout", headers=headers)
    print(r.json())
    ```
  </CodeGroup>
</RequestExample>

***

### Download SAML service-provider metadata

<Note>
  `GET /auth/saml/{orgSlug}/metadata`
</Note>

Returns Orbit's SP-side SAML 2.0 metadata as XML. IdP administrators paste this document (or upload the downloaded file) into their SAML application configuration to register Orbit as a service provider — it carries the entity ID, ACS URL, and SP signing details. Served as `application/xml` with a `Content-Disposition: attachment` so it downloads cleanly, and cached at the edge because it changes only on entity rotation.

<ParamField path="orgSlug" type="string" required>
  URL-safe organization slug that selects the SAML configuration.
</ParamField>

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl "https://api.orbit.devotel.io/auth/saml/{orgSlug}/metadata" \
      -H "X-API-Key: dv_live_sk_your_key_here"
    ```

    ```typescript Node.js theme={null}
    const res = await fetch('https://api.orbit.devotel.io/auth/saml/{orgSlug}/metadata', {
      method: 'GET',
      headers: {
        'X-API-Key': process.env.ORBIT_API_KEY!
      }
    });
    const data = await res.json();
    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    r = requests.get("https://api.orbit.devotel.io/auth/saml/{orgSlug}/metadata", headers=headers)
    print(r.json())
    ```
  </CodeGroup>
</RequestExample>

***

### Consume the SAML assertion (ACS)

<Note>
  `POST /auth/saml/{orgSlug}/callback`
</Note>

SAML 2.0 Assertion Consumer Service. The identity provider POSTs a signed `SAMLResponse` here after the user authenticates; Orbit verifies the signature, audience and replay window, provisions a user on first login, then 302-redirects the browser to the dashboard sign-in ticket so the session cookie can be minted. This endpoint is called by the IdP, not directly by your application.

<ParamField path="orgSlug" type="string" required>
  URL-safe organization slug that selects the SAML configuration.
</ParamField>

<RequestExample>
  <CodeGroup>
    ```bash cURL theme={null}
    curl -X POST "https://api.orbit.devotel.io/auth/saml/{orgSlug}/callback" \
      -H "X-API-Key: dv_live_sk_your_key_here"
    ```

    ```typescript Node.js theme={null}
    const res = await fetch('https://api.orbit.devotel.io/auth/saml/{orgSlug}/callback', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.ORBIT_API_KEY!
      }
    });
    const data = await res.json();
    ```

    ```python Python theme={null}
    import os, requests

    headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
    r = requests.post("https://api.orbit.devotel.io/auth/saml/{orgSlug}/callback", headers=headers)
    print(r.json())
    ```
  </CodeGroup>
</RequestExample>

***