Skip to main content
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

1

Your frontend asks your backend for credentials

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

Your backend calls the TORTUS launch endpoint

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

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:
PartValue
UsernameYour client ID (e.g. cli_abc123xyz)
PasswordYour 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

​
Request body

All fields are optional. Send what’s relevant to your integration.
​
userId
string
Existing TORTUS user ID from a previous session. Provide this to resume a user’s session.
​
externalUserId
string
Your internal user ID, stored for reference.
​
userPayload
object
User information to associate with this session.

​
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
}
​
launch_token
string
The token to pass to the SDK. Valid for 5 minutes.
​
user_id
string
The TORTUS user ID for this session. Save it to resume the session later via userId.
​
expires_in
number
Seconds until the token expires.

​
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.