Token Lifecycle

Understand how access tokens are issued, when they expire, how to refresh them, and best practices for secure storage.

Access Token Issuance

After a successful login flow, your backend receives two tokens from rNet: an access token and a refresh token. The access token is a short-lived JWT that authorizes your app to make AI requests on behalf of the user.

TokenPurposeLifetime
Access TokenAuthorizes AI API requests on behalf of the userShort-lived (minutes to hours)
Refresh TokenUsed to obtain a new access token without re-loginLong-lived (days to weeks)

Token Expiration

Access tokens are intentionally short-lived for security. When a token expires, AI requests will fail with a 401 Unauthorized error. Your backend should detect this and refresh the token automatically.

Refreshing Tokens

1

Detect Expiration

Check the expires_in value from the initial token response, or catch 401 errors from AI requests.
2

Call Refresh Endpoint

Use the SDK's refreshAccessToken() method with the stored refresh token.
3

Update Session

Replace the old access token in your session with the new one. The refresh token may also be rotated.
javascript
// Refresh the access token when it expires
app.post('/refresh', async (req, res) => {
  try {
    const tokens = await auth.refreshAccessToken(
      req.session.rnet.refreshToken
    );
    req.session.rnet.accessToken = tokens.access_token;
    if (tokens.refresh_token) {
      req.session.rnet.refreshToken = tokens.refresh_token;
    }
    res.json({ ok: true });
  } catch (err) {
    // Refresh token is also expired, user must log in again
    req.session.rnet = null;
    res.status(401).json({ error: 'Session expired. Please log in again.' });
  }
});

Handling Invalid or Expired Tokens

ScenarioAction
Access token expiredRefresh using the refresh token
Refresh token expiredRedirect user to login again
Token malformed or revokedClear session, redirect to login
AI request returns 401Attempt refresh once, then redirect to login if it fails

Secure Storage Best Practices

  • Always store tokens on the backend: use server-side sessions or encrypted HttpOnly cookies.
  • Never use localStorage or sessionStorage: these are vulnerable to XSS attacks.
  • Set HttpOnly, Secure, and SameSite flags on session cookies.
  • Rotate refresh tokens if the server returns a new one during refresh.
  • Clear tokens on logout: destroy the session and remove cookies.
javascript
// Secure cookie configuration
res.cookie('rnet_session', encryptedSessionId, {
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'lax',
  maxAge: 60 * 60 * 1000 // 1 hour
});
Security Note
Never expose your client_secret or tokens to the frontend. All token exchange and refresh operations must happen securely on your backend server.

Sign Out & Ending Sessions

When a user signs out, your application must clear all locally stored authentication state, including access tokens, refresh tokens, and session cookies.

Logout Steps

1

Destroy the Application Session

Clear the user's server-side session data, including stored access and refresh tokens.
2

Remove Session Cookies

Clear any cookies used to maintain the authenticated session (e.g., rnet_session, pkce_verifier).
3

Redirect the User

Send the user to a signed-out landing page or your app's home page. A fresh PKCE login will be required for any future rNet-backed requests.
javascript
app.get('/logout', (req, res) => {
  // Clear rNet tokens from session
  req.session.rnet = null;

  // Remove session cookies
  res.clearCookie('rnet_session');

  // Destroy the entire session
  req.session.destroy(() => {
    res.redirect('/');
  });
});
Next
Learn how AI credits are consumed across applications in Credit Usage.

Quick Reference Links