How to Handle Authentication Tokens in Retool

Navigate to Settings → Resources and open the resource that uses OAuth 2.0. In the authentication section, ensure 'OAuth 2.0' is selected as the auth type. Find the 'Access token URL' field and verify it points to the OAuth provider's token endpoint (e.g., https://api.service.com/oauth/token). Enable 'Refresh token' if the option is available. Set the 'Refresh token URL' (often the same as the access token URL). Retool will automatically use the refresh token to obtain a new access token before the current one expires, preventing 401 errors in production.

Retool resources support two authentication modes: (1) Shared credentials — one set of credentials used by all users of the app. Appropriate for service-to-service APIs where you own a service account. (2) Per-user OAuth — each Retool user authenticates with the external service using their own account. Data operations are scoped to that user's permissions. Per-user OAuth is configured in the resource settings under 'Authentication type' → 'OAuth 2.0 (per user)'. Users see a 'Connect your account' button the first time they use the app.

For APIs that use static bearer tokens (not OAuth), store the token as a Retool environment variable, not hardcoded in query bodies. Navigate to Settings → Environment Variables (or Settings → Configuration Variables). Create a new variable named 'EXTERNAL_API_TOKEN', mark it as 'Secret', and enter the token value. In your REST API queries, set the Authorization header to: Bearer {{ environment.variables.EXTERNAL_API_TOKEN }}. Secret variables are encrypted at rest and not visible to non-admin users.

1// REST API resource header configuration:
2// Header: Authorization
3// Value: Bearer {{ environment.variables.EXTERNAL_API_TOKEN }}
4
5// Or in a JS Query making a fetch call (avoid this — use resource queries):
6// fetch(url, {
7//   headers: {
8//     'Authorization': `Bearer ${environment.variables.EXTERNAL_API_TOKEN}`
9//   }
10// });

When debugging authentication issues, you may need to inspect a JWT token's payload. Write a JS Query to decode the JWT payload (the middle section, base64-encoded). Never log or display the full JWT in UI components — only decode it in the DevTools console or a temporary debug query. The decoded payload shows the token's claims: user ID, expiry time, scopes, and audience.

1// JS Query: inspectJWT (for debugging only — remove from production)
2// Decodes the JWT payload without verifying signature
3
4const token = environment.variables.JWT_TOKEN;
5
6if (!token) {
7  console.log('No JWT token found in environment variables');
8  return null;
9}
10
11try {
12  // JWT has three sections: header.payload.signature
13  const parts = token.split('.');
14  if (parts.length !== 3) throw new Error('Not a valid JWT format');
15
16  // Decode the payload (middle section)
17  const payload = JSON.parse(atob(parts[1].replace(/-/g, '+').replace(/_/g, '/')));
18
19  const now = Math.floor(Date.now() / 1000);
20  const expiresIn = payload.exp - now;
21
22  console.log('JWT payload:', JSON.stringify(payload, null, 2));
23  console.log(`Token expires in: ${expiresIn} seconds (${(expiresIn / 60).toFixed(1)} minutes)`);
24
25  return {
26    sub: payload.sub,
27    exp: new Date(payload.exp * 1000).toISOString(),
28    expiresInSeconds: expiresIn,
29    isExpired: expiresIn < 0,
30    scopes: payload.scope || payload.scopes,
31  };
32} catch (err) {
33  console.error('Failed to decode JWT:', err.message);
34  return null;
35}

Even with refresh token configuration, token errors can occur. Add an 'On failure' event handler to critical API queries that checks for 401 errors. If the error is authentication-related, show a user-friendly message and provide a 'Reconnect' button that triggers the OAuth re-authorization flow. For apps with shared credentials, the error handler can also alert an admin via utils.showNotification().

1// Query 'On failure' event handler (JS Query)
2// Triggered when an API query returns a 401 or 403 error
3
4const error = query1.error;
5const statusCode = error?.statusCode || error?.response?.status;
6
7if (statusCode === 401) {
8  utils.showNotification({
9    title: 'Session expired',
10    description: 'Your session has expired. Please reconnect your account.',
11    notificationType: 'warning',
12    duration: 10,
13  });
14  // Show reconnect UI
15  await reconnectBanner.setValue(true);
16} else if (statusCode === 403) {
17  utils.showNotification({
18    title: 'Access denied',
19    description: 'You do not have permission to perform this action.',
20    notificationType: 'error',
21  });
22} else {
23  utils.showNotification({
24    title: 'API error',
25    description: `Request failed: ${error?.message || 'Unknown error'}`,
26    notificationType: 'error',
27  });
28}