Security & Token Handling

Secrets, JWT safety, refresh token flow.

therappai uses industry-standard JWT authentication to keep user data secure. Your application is responsible for storing tokens safely, refreshing them correctly, and preventing exposure of sensitive data. This guide outlines the recommended practices for secure, reliable integrations in both consumer apps and enterprise environments.

---

Token Types

therappai issues two tokens when a user logs in:

Access Token

• Short-lived

• Required for all authenticated API calls

• Sent via Authorization: Bearer header

Refresh Token

• Long-lived

• Used to obtain new access tokens

• Must never be exposed to client-side code in web apps

• Should only be stored in secure storage

Both tokens are tied to the authenticated user.

---

Where to Store Tokens

Correct storage depends on your platform:

---

Mobile Apps (iOS / Android)

Use secure storage only:

• iOS → Keychain

• Android → Encrypted SharedPreferences

Never store tokens:

• in AsyncStorage

• in plain preferences

• in logs

• in unencrypted files

---

Web Apps

Best practice:

Access token → in memory or encrypted local storage

Refresh token → HTTP-only secure cookie (server-set)

Avoid:

• storing refresh tokens in localStorage

• embedding tokens in URLs

• exposing tokens in console logs

---

Backend or Server-Side Apps

Safe options:

• environment variables

• encrypted database fields

• secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager)

Never:

• commit tokens to Git

• store in plaintext config files

• use them directly in frontend code

---

Refreshing Access Tokens

Access tokens expire for safety. When an API call returns a token-expired response:

1. Use /refresh/ with the refresh token

2. Replace the old access token

3. Retry the request

If refreshing fails, the user must log in again.

Avoid “silent refresh loops”

Always stop refreshing after a few attempts. This prevents infinite loops if a refresh token is invalid.

---

Session Expiry & Logout

A clean logout flow should:

• delete the access token

• delete the refresh token

• clear secure storage

• return the user to a login/onboarding screen

This prevents unauthorized access on shared devices.

---

Preventing Token Exposure

Follow these rules in all production applications:

Do NOT:

• expose tokens in client-side logs

• include tokens in error reports

• send tokens in URLs or query params

• store tokens in browser cookies without HttpOnly

• hardcode tokens in your source code

• push tokens to GitHub

DO:

• sanitize logs

• mask tokens in any error output

• rotate refresh tokens periodically

• use HTTPS only (never http)

• implement basic rate limiting on login attempts

---

Handling Token Compromise

If you suspect a token may be compromised:

1. Invalidate the access token

2. Invalidate the associated refresh token

3. Force the user to re-authenticate

4. Consider device-level logout in mobile apps

therappai will not automatically revoke tokens unless explicitly instructed.

---

Common Security Patterns (Recommended)

Pattern 1 — Mobile App

• Store tokens in secure device storage

• Refresh access tokens silently when needed

• Never log the refresh token

Pattern 2 — Web App with Backend

• Backend stores the refresh token

• Frontend stores only access token

• Backend rotates refresh tokens as needed

Pattern 3 — Server-to-Server Integration

• Store tokens in a secure secrets manager

• Rotate tokens regularly

• Restrict access via IAM policies

---

Summary

To ensure secure and reliable integrations:

• Treat access & refresh tokens as highly sensitive

• Use secure storage appropriate to each platform

• Refresh tokens safely and thoughtfully

• Use HTTPS for all API calls

• Never expose tokens in logs, URLs, or client bundles

Following these practices helps you protect user data and maintain the integrity of your application.