# Security & Token Handling

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.