> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rollfi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Single Sign-On

## High Level Overview

Rollfi supports a streamlined single sign-on flow for embedded partners that want to move a signed-in user from their product into Rollfi without a separate username, password, or two-factor step.

In the SSO model, your application authenticates to Rollfi, requests a login link for a known user, and Rollfi returns a short-lived redirect URL that contains a signed JWT.

> For more in depth information and examples, please refer to the [Rollfi SSO API reference](https://developer.rollfi.xyz/api-reference/sso/getSsoRedirectLink).

## How The Flow Works

1. Your application signs the user in on your side.
2. Your backend calls Rollfi using Basic authentication with your `clientId` and `clientSecret`.
3. Your backend sends the user context needed for login.
4. Rollfi validates the request and confirms the user is allowed to access the requested company.
5. Rollfi creates a short-lived JWT and appends it to a Rollfi login URL.
6. Your application redirects the user to that URL.

```mermaid theme={null}
sequenceDiagram
  autonumber
  participant User
  participant Partner as Partner App
  participant Backend as Partner Backend
  participant Rollfi as Rollfi SSO API

  User->>Partner: Sign in
  Partner->>Backend: Request Rollfi SSO login
  Backend->>Rollfi: getSsoRedirectLink\n(Basic auth + user context)
  Rollfi->>Rollfi: Validate client + user/company access
  Rollfi->>Rollfi: Create short-lived RS256 JWT
  Rollfi-->>Backend: Return loginUrl with JWT
  Backend-->>Partner: Return loginUrl
```

7. Use the `loginUrl` to redirect the user into Rollfi. The JWT is validated and the user is logged in automatically.

## What Rollfi Puts In The JWT

Rollfi creates the login JWT with these core attributes:

* `companyId`
* `email`
* `iat`
* `exp`
* `roles` when roles are supplied
* `nbf` when clock tolerance is applied

The token is signed with `RS256` using a Rollfi-managed private key.

## Example Request

```json theme={null}
{
  "method": "getSsoRedirectLink",
  "email": "user@example.com",
  "companyId": "YOUR_COMPANY_ID",
  "roles": ["w2Employee"]
}
```

## Example Response

```json theme={null}
{
  "success": true,
  "loginUrl": "https://app.rollfi.xyz/...?...jwt=SIGNED_TOKEN"
}
```

## Security Model

The current flow uses two layers of protection:

* API authentication between your backend and Rollfi using your `clientId` and `clientSecret`
* JWT signing by Rollfi using `RS256` so the final login URL cannot be tampered with

This design keeps the Rollfi signing key on the Rollfi side while still allowing your application to control when a user should be redirected into Rollfi.

## When To Use The SSO Model

The current Rollfi-signed redirect flow is a strong fit when:

* You want the simplest partner implementation
* You want to redirect users from your application without having to worry about the friction of logging them in, or handling authentication