Authentication

This page describes how a T-Suite session is established and checked, and which extra verification steps protect sensitive actions. It explains behaviour; it is not a contract for an integration. Integrations are agreed with Libertum first — see Developers.

Sign-in flow

Every sign-in has at least two steps, and a third when two-factor authentication is on:

1. Email and password. The user submits their credentials. If they are correct, the platform does not issue a session yet — it sends a one-time code to the user’s email.
2. Email code. The user submits the code. An email code is required on every sign-in, not just the first one.
3. Authenticator code (if 2FA is on). If the account has two-factor authentication enabled, the email step returns a short-lived intermediate token instead of a session. The user then submits a 6-digit code from their authenticator app — or one of their backup codes — together with that token.

Only after the last step does the platform return an access token.

Sessions and access tokens

• Bearer token. Authenticated requests carry the access token in the Authorization header as Bearer followed by the token.
• One active session per account. The platform pins the current access token for each account server-side. Signing in again — on another device or browser — replaces the pinned token, and the previous token stops working. Signing out removes it.
• Fixed lifetime, no refresh endpoint. Access tokens expire after a fixed period. There is no token-refresh call; when a token expires, the user signs in again.
• Blocked accounts. If an administrator deactivates an account, its next request is refused and the session is cleared.

Typical responses when a session is not usable:

Status	Meaning
401	No token, an invalid or expired token, or a token that has been replaced by a newer sign-in
403	The account has 2FA enabled but the authenticator step has not been completed, or the account is blocked
503	The session store is temporarily unavailable — retry later rather than signing the user out

Two-factor authentication

Users can turn on two-factor authentication from their account settings:

• Authenticator app (TOTP). The user scans a QR code with any standard authenticator app and confirms with a first code.
• Backup codes. When 2FA is turned on, the user receives 8 single-use backup codes. Each code works once; the platform stores them only in hashed form, shows how many unused codes remain, and lets the user regenerate a fresh set.
• A backup code is accepted anywhere an authenticator code is — at sign-in and for step-up verification.

Step-up verification for sensitive actions

Some actions need a fresh proof of identity even inside a valid session:

Action	Verification
Custodian Wallet withdrawal	An email code (6 digits, valid for 10 minutes), or an authenticator code, or one of the backup codes
Signing an investment agreement	A one-time code is requested and confirmed before the signature is recorded
Signing Structuring documents	A one-time code confirms the signature

Requests for withdrawal verification codes are rate-limited.

Withdrawals carry further controls beyond the code — a saved address that is at least 24 hours old, per-transaction and daily limits, and Libertum approval above a threshold. See the Custodian Wallet page.

The onboarding gate

A valid session is not, by itself, enough for financial operations. Most product routes (orders, offerings, transfers, the Custodian Wallet, Distribution Hub, Structuring and others) also check that the user has finished onboarding:

1. An active subscription — the free Investor plan counts.
2. Approved identity verification — KYC for individuals, KYB for institutions (both through SumSub).
3. Manual account approval, where a deployment requires it.

If a step is missing, the API answers 403 with requiresOnboarding: true and a missingStep value (subscription, kyc, kyb or approval), so a client can send the user to the right screen without parsing the message text.

Profile, KYC and settings routes stay reachable during onboarding, so the user can complete it.

Server-to-server calls

Libertum’s own administrative tooling does not call the marketplace API with a user session. Its requests travel server-to-server through an admin proxy, and every request is signed with an HMAC that the marketplace API verifies before acting. These administrative routes are not available to customers or integrators.

Inbound callbacks from providers such as SumSub and Stripe are likewise verified by signature before they are processed.

Whitelabel tenant resolution

The same API serves Libertum’s own app and every whitelabel tenant’s custom domain. The API works out which tenant a request belongs to from the domain the app is served on, and uses that to apply the tenant’s branding, its marketplace scope and its settings.

Browser requests are accepted only from Libertum’s own origins and from verified tenant domains. A custom domain that has not completed domain verification cannot call the API from a browser.

API keys (Stablecoin Studio only)

The one place where a machine credential is used today is the Stablecoin Studio developer API: an issuer creates and revokes API keys from the Developer page in Stablecoin Studio, and each key can read only that issuer’s own data. All other API access uses a user session as described above. See API overview.