If you've ever built an application that uses OAuth2 or OpenID Connect for authentication, you've probably run into this problem: your users get unexpectedly logged out. They're in the middle of filling out a form, reviewing data, or simply using the application — and suddenly they're redirected to a login screen. Their work is lost, and they're frustrated.

This happens because access tokens — the credentials your application uses to call protected APIs — are designed to be short-lived. A typical access token expires after an hour or two. That's good for security: if a token is compromised, the damage is limited. But it's terrible for user experience.

The solution is a well-established mechanism called refresh tokens. The idea is straightforward:

• Your application receives two tokens when the user logs in: a short-lived access token and a long-lived refresh token.
• The access token is used for API calls as usual.
• When the access token expires, your application uses the refresh token to silently obtain a new access token — no login screen, no user interaction.
• The user keeps working without interruption.

This is not a new concept — it's part of the OAuth2 standard — but implementing it correctly requires proper server-side support.

With TMS Sphinx 2.0, refresh token support is now built directly into the authentication server. No custom hacks, no workarounds, and no need to resort to insecure long-lived access tokens.

Introducing TMS Sphinx

TMS Sphinx is the authentication and authorization server of the TMS BIZ suite. It implements OAuth2 and OpenID Connect for Delphi-based systems, handling identity, tokens, and security so your applications don't have to.

Version 2.0 introduces native refresh token support, fully integrated with existing OAuth2/OIDC flows.

Full list of changes:
https://doc.tmssoftware.com/biz/sphinx/guide/release-notes.html#version-20-feb-2026

Enabling Refresh Tokens in Sphinx

Enabling refresh tokens requires two things:

1. Allow the refresh_token grant type for your client application.
2. Allow the offline_access scope, which signals that the client wants long-lived access.

When a client requests the offline_access scope during authorization, Sphinx will issue a refresh token alongside the access token.

Example configuration:

  Client := SphinxConfig.Clients.Add;
  Client.ClientId := 'myapp';
  Client.DisplayName := 'My Application';
  Client.RequireClientSecret := False;
  Client.AllowedGrantTypes := [gtAuthorizationCode, gtRefreshToken];
  Client.ValidScopes.Add('openid');
  Client.ValidScopes.Add('email');
  Client.ValidScopes.Add('offline_access');  // Required for refresh tokens

The default access token lifetime is 2 hours and the default refresh token lifetime is 30 days. You can customize both per client:

  Client.AccessTokenLifetime := 3600;          // 1 hour (in seconds)
  Client.RefreshTokenLifetime := 3600 * 24 * 14; // 14 days (in seconds)

Short-lived access tokens stay short-lived — security preserved.

Token Flow: What Actually Happens

Here's the real-world sequence your application uses.

1. Initial Login

The user logs in normally using OAuth2 / OpenID Connect. The client requests the offline_access scope.

Sphinx issues:

{
  "access_token": "eyJhbGciOiJIUzI1...",
  "expires_in": 3600,
  "refresh_token": "def50200a94f...",
  "token_type": "Bearer"
}

Your app stores:

• Access token (memory)
• Refresh token (secure storage)

2. Normal API Calls

GET /api/orders
Authorization: Bearer eyJhbGciOiJIUzI1...

Everything works as usual — until the access token expires.

3. Access Token Expired? Refresh Silently

Instead of redirecting the user to /login, the app refreshes the token:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=def50200a94f...
&client_id=myapp

Sphinx responds:

{
  "access_token": "eyJhbGciOiJIUzI1...",
  "expires_in": 3600,
  "refresh_token": "def50200bb17...",
  "token_type": "Bearer"
}

Notice the new refresh_token in the response — Sphinx implements refresh token rotation. The old token is invalidated, and your app must store the new one. This rotation mechanism helps detect token theft: if a consumed token is reused, Sphinx rejects it immediately.

No UI changes. No user interaction. No broken flow.

What Sphinx Handles for You

With refresh tokens enabled, TMS Sphinx 2.0 automatically manages:

• Refresh token issuance
• Token expiration and renewal
• Refresh token rotation
• Token revocation
• Per-client and per-user session control

All of this follows OAuth2 / OpenID Connect best practices.

Full technical details:
https://doc.tmssoftware.com/biz/sphinx/guide/refresh-tokens.html

Perfect Fit for Modern Apps

Refresh tokens are especially valuable for:

• Single-page applications (SPAs)
• Desktop apps with long-running sessions
• Mobile apps that stay logged in for weeks
• Any system where re-authentication hurts usability

Instead of engineering fragile "remember me" logic, you rely on a standard, proven mechanism.

Final Thoughts

Refresh tokens are one of those features users never notice — and that's exactly why they're so important.

With TMS Sphinx 2.0, you can:

• Keep users logged in longer
• Avoid insecure long-lived access tokens
• Improve UX without compromising security
• Rely on a production-ready authentication framework

Learn more:

• TMS Sphinx 2.0 Release Notes
  https://doc.tmssoftware.com/biz/sphinx/guide/release-notes.html#version-20-feb-2026
• Refresh Tokens Documentation
  https://doc.tmssoftware.com/biz/sphinx/guide/refresh-tokens.html