Authentication & Tokens

This article documents authentication patterns used by CJH, token types, and operational best practices for issuing, storing and rotating tokens.

Authentication model (overview)

• CJH requires authentication for API calls; user sessions are validated server-side before access is granted. Many client components call a server-side auth library (the repo uses Supabase client calls in components). Example client call pattern: supabase.auth.getUser(). :contentReference[oaicite:3]{index=3}

Token types & usage

• Access tokens (short-lived): Used for authenticating API calls from clients (PWA/native). Prefer short lifetimes (minutes to hours).
• Refresh tokens: Used to obtain new access tokens without re-prompting the user. Store securely server-side or in secure storage on the client per platform best practice.
• Service tokens / API keys (longer-lived): For server-to-server integrations. These must be treated as secrets and kept server-side. Example: payment provider secret keys, Mapbox secret (if used server-side). :contentReference[oaicite:4]{index=4}

Client vs server tokens

• Client-facing tokens (JWT access tokens, public Mapbox pk.* tokens) may be present in the client; never include secret tokens (sk.*) in frontend bundles. The Jobs Map doc explicitly cautions against exposing client-side secrets. :contentReference[oaicite:5]{index=5}
• Server-only tokens should be stored in a secrets manager and never baked into a public build.

Storage recommendations

• Web (PWA): Keep access tokens in secure cookies (HttpOnly, Secure, SameSite) or local secure storage with XSRF protections. Avoid persistent storage of long-lived secrets.
• Native apps: Use platform secure storage (Keychain on iOS, Keystore on Android).
• Server: Store secret tokens and service account keys in a secrets manager and grant minimal privileges to the runtime environment.

Rotation, revocation & logout

• Rotation: Rotate service/API keys regularly and document rotation procedures. Have a roll-back process if the new key breaks integrations.
• Revocation: Implement server-side token revocation lists or short-lived tokens with refresh to allow immediate session disabling.
• Logout & session expiry: Provide explicit logout and session expiry handling and force re-authentication for sensitive operations.

Security best practices

• Use HTTPS for all token exchanges.
• Protect token endpoints with rate limiting and detection of abnormal access patterns.
• Log authentication events for audit and correlation with suspicious activity.

Developer notes

• If using Supabase or a provider with JWT, ensure JWT claims include tenant/org id to simplify server-side scoping. Use the claims for RLS enforcement or server checks (see RLS & Data Scoping).

Updated on: 10/01/2026