Authentication

The SDK authenticates each session with a short-lived launch token. You mint this token on your secure backend and hand it to the client through the fetchClientSecrets callback.

Never expose your client ID or client secret to the frontend, and never mint launch tokens in the browser. Always retrieve them from a backend you control.

How it fits together

Your frontend asks your backend for credentials

The SDK calls your fetchClientSecrets function, which hits a route on your own server.

Your backend calls the TORTUS launch endpoint

Authenticated with your client ID and secret, your server requests a launch token.

Your backend returns the launch token

The SDK exchanges the token to load and authenticate the embedded app.

The launch endpoint

Authenticate with HTTP Basic Authentication using your TORTUS-provided credentials:

Part	Value
Username	Your client ID (e.g. `cli_abc123xyz`)
Password	Your client secret (e.g. `sec_def456uvw`)

Base64-encode clientId:clientSecret and send it in the Authorization header.

POST https://api.tortus.ai/v1/oauth/launch

POST https://api.staging.tortus.ai/v1/oauth/launch

Request body

All fields are optional. Send what’s relevant to your integration.

string

To help identify and resume the correct user, send their first and last name on every launch. After their first launch, also send the returned userId. Include any other fields relevant to your integration.

If you don’t send userId for someone who has launched before, TORTUS creates a new user every time. Store the user_id you get back and resend it on every launch. See Persisting and resuming users.

string

Your own internal user ID, kept as a reference label on the TORTUS user. This is not a resume or lookup key: sending it does not match an existing user. Only userId resumes a user.

object

User information to associate with this session.

Show userPayload

string

User’s email address.

string

User’s first name.

string

User’s last name.

string

External organisation identifier (e.g. ODS code, facility ID).

string

External organisation name, for display purposes.

object

Custom metadata, such as department or role.

Response

If the user doesn’t already exist, TORTUS creates one and returns it in the response. A newly created user only becomes valid once the launch token has been exchanged.

{
  "launch_token": "AbCdEfGhIjKlMnOp.QrStUvWxYzAbCdEfGhIjKlMnOpQrStUvWxYz",
  "user_id": "tortus|a1b2c3d4e5f6g7h8",
  "expires_in": 300
}

string

The token to pass to the SDK. Valid for 5 minutes.

string

The TORTUS user ID for this session. Save it to resume the session later via userId.

number

Seconds until the token expires.

Persisting and resuming users

Each launch either resumes an existing TORTUS user or creates a new one. Which one you get depends entirely on whether you send userId. The rule is simple:

First launch for a person: call the endpoint without userId (optionally with externalUserId and userPayload). Then use user_id from the response and save it against that person in your own system.
Every later launch for the same person: send that saved value as userId to resume them.

Skip step 1’s save, or forget to send userId in step 2, and you create a duplicate user on every login. Here is the same loop in your launch route:

// server-side route, e.g. GET /api/tortus/client-secrets
const credentials = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64');

// Look up the TORTUS user ID you saved for this person, if any.
const savedUserId = await getTortusUserId(currentUser.id);

const response = await fetch('https://api.tortus.ai/v1/oauth/launch', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    // Resume the existing user when you have their ID.
    ...(savedUserId ? { userId: savedUserId } : {}),
    externalUserId: currentUser.id,
    userPayload: { email: currentUser.email },
  }),
});

const { launch_token, user_id } = await response.json();

// First time round, persist the returned ID so future launches resume this user.
if (!savedUserId) {
  await saveTortusUserId(currentUser.id, user_id);
}

// Return { launchToken: launch_token } to your frontend.

Wiring it into the SDK

Return the token from fetchClientSecrets. The SDK calls this whenever it needs fresh credentials.

const client = await loadTortus({
  publishableKey: 'pk_your_key_here',
  container: '#tortus-container',
  environment: 'production',
  fetchClientSecrets: async () => {
    const response = await fetch('/api/tortus/client-secrets');
    const data = await response.json();
    return { launchToken: data.launchToken };
  },
});

Because tokens are short-lived, have your backend mint a fresh one on each call rather than caching it client-side.

Getting started

Core concepts

Guides

Reference

Changelog

How it fits together

The launch endpoint

Request body

Response

Persisting and resuming users

Wiring it into the SDK

​How it fits together

​The launch endpoint

​Request body

​Response

​Persisting and resuming users

​Wiring it into the SDK

How it fits together

The launch endpoint

Request body

Response

Persisting and resuming users

Wiring it into the SDK