Embedded iframe SSO

Overview

How it works

Use this when your product embeds Tarot Routing in an iframe and you want the user already logged in, without showing a Tarot login form.

The flow is:

1. Create an API key whose role includes the delegated_login access level.
2. From your server, mint a short-lived (60s) user refresh token for that user’s email.
3. Immediately load the iframe with that token in the authtoken query parameter.

Tarot logs the user in inside the iframe. The sections below cover each step in detail.

Enablement

Enablement

1. Get an API key in Tarot Routing. Generate keys at route.optimiser.app or via Admin Panel → User Management → API Keys. See Getting an API key.
2. Ensure the API-key identity’s role includes the delegated_login access level.

Mint

Mint a user refresh token

From your server, call:

POST /v3/core/auth/delegated_token

Body:

{ "email": "planner@example.com" }

Send the API key in the request header:

curl -X POST "https://api.optimiser.app/v3/core/auth/delegated_token" \
  -H "X-Tarot-API-Key: $TAROT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"email": "planner@example.com"}'

import os, requests

response = requests.post(
    "https://api.optimiser.app/v3/core/auth/delegated_token",
    headers={"X-Tarot-API-Key": os.environ["TAROT_API_KEY"]},
    json={"email": "planner@example.com"},
)
response.raise_for_status()
refresh_token = response.json()["refresh_token"]

const response = await fetch(
  "https://api.optimiser.app/v3/core/auth/delegated_token",
  {
    method: "POST",
    headers: {
      "X-Tarot-API-Key": process.env.TAROT_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email: "planner@example.com" }),
  },
);

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const { refresh_token } = await response.json();

Response:

{
  "access_token": "<user v2 JWT, sub=user:{id}, ~15m>",
  "refresh_token": "<user refresh JWT, ~60s>",
  "refresh_token_expiry": "…"
}

refresh_token is a short-lived (60s) user refresh JWT. Use that value. Ignore access_token and refresh_token_expiry.

Iframe handoff

Iframe handoff

Put the minted refresh JWT in the iframe URL immediately after minting:

https://route.optimiser.app/?authtoken=<refresh_token>

The user will be logged in in the iframe.