SSO launch links

Overview

SSO launch links let you redirect a user from your application into the Tilt POS already authenticated, without a separate login step.

Tilt uses a magic-link / launch-token pattern. Your server mints a short-lived signed token via a server-to-server API call; you redirect the user’s browser to the token URL; Tilt exchanges the token for a session and drops the user at the sale page.

Flow

1. Your server calls POST /pos/v1/launch-tokens with the user’s external ID, location_id, and optional role_slug
2. Response includes a launch_url (valid for 10 minutes, single-use)
3. Redirect the user’s browser to launch_url
4. Tilt automatically provisions a POS user account for the (partner_id, external_user_id) pair on first use and grants the specified role at the location
5. User lands at /sale already authenticated

Mint a launch token

POST /pos/v1/launch-tokens

Required scope: tilt/pos:launch

{
  "external_user_id": "user-9912",
  "display_name": "Alex Rivera",
  "location_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "role_slug": "location_cashier"
}

Field	Type	Required	Description
external_user_id	string	Yes	Stable, immutable ID for this user in your system. Always maps to the same POS account.
display_name	string	No	Name shown in POS header and audit log. Kept from previous launch if omitted.
location_id	UUID	Yes	The location the user is signing in to. Determines the POS landing page and, on first provision, the membership role.
role_slug	string	No	Role granted on first provision only. Ignored on subsequent launches. Allowed: location_cashier (default), location_supervisor.

Response:

{
  "launch_url": "https://pos.dev.apps.myfinterra.com/launch?token=eyJ…",
  "expires_at": "2026-05-12T10:40:00Z"
}

Redirect the user to launch_url immediately after minting. The token expires after 10 minutes and is single-use.

User provisioning

On first use of a given external_user_id, Tilt:

1. Creates a pos_user_tbl account anchored to your partner
2. Creates a pos_user_membership_tbl row granting role_slug at location_id
3. Exchanges the token for a Cognito session and redirects to /sale

On subsequent uses, the existing account is reused — no new provisioning. The role_slug and display_name on subsequent requests are ignored (existing membership is unchanged).

Permissions granted by role

Role	Permissions
location_cashier	pos.order.read, pos.order.create, pos.payment.initiate, pos.payment.refund, pos.payment.void, pos.customer.read, pos.customer.create
location_supervisor	All cashier permissions plus pos.order.override, pos.report.read, pos.settings.read

Session lifetime

A launched session has the same TTL as a regular POS login (8 hours). Sign-out works normally from within the POS.

Security

• The launch_url is valid for 10 minutes — generate it immediately before redirecting
• It is single-use — a second attempt with the same token returns 410 Gone
• The token is HMAC-SHA256 signed with a server-side key; it cannot be forged
• Always generate launch tokens server-side; never expose your client_secret to a browser