Skip to content

Authentication

Jump to bottom
Niccanor Dhas edited this page Feb 22, 2026 · 1 revision

Authentication

tmam supports three authentication methods for signing in to the dashboard, plus a separate key-based auth system for the SDK.

Dashboard Authentication

Email & Password

The default sign-in method. Users create an account with their name, email, and password.

Registration flow:

  1. User submits name, email, and password via /register
  2. Password is hashed with bcrypt (configurable SALT_ROUNDS, default 12)
  3. A confirmation email is sent via SendGrid containing a unique verification link
  4. User clicks the link → account is verified and fully activated
  5. User can now sign in

Sign-in flow:

  1. User submits email and password
  2. Server validates credentials and issues an RSA-signed JWT
  3. JWT is stored server-side and cross-validated on every protected request

Google Sign-In

One-click sign-in with a Google account. No password required.

Setup (self-hosted):

  1. Create OAuth 2.0 credentials at console.cloud.google.com → APIs & Services → Credentials
  2. Add your dashboard URL as an authorized redirect URI (e.g. http://localhost:3001)
  3. Set in server/src/.env:
    GOOGLE_CLIENT_ID=your_client_id.apps.googleusercontent.comGOOGLE_CLIENT_SECRET=your_client_secret
  4. Set the same GOOGLE_CLIENT_ID in web-client/.env

When a user signs in with Google for the first time, a new account is created automatically using their Google profile name and email. No email confirmation is required for Google sign-ins.

Forgot Password

Users who signed up with email/password can request a reset link.

Reset flow:

  1. User submits their email at /forgot-password
  2. Server generates a time-limited reset token
  3. A password reset email is sent via SendGrid with a link valid for 24 hours
  4. User clicks the link → can set a new password

Email Notifications

tmam sends the following transactional emails via SendGrid:

Trigger | Subject | Content -- | -- | -- New registration | "Confirm Your Email" | Verification link Forgot password | "Reset Your Password" | Reset link (24h expiry) Team invitation | "You're invited to join [Org]" | Invitation with role details

Endpoints that require a verified account return 401 Unauthorized if the account has not confirmed its email.

# Authentication

tmam supports three authentication methods for signing in to the dashboard, plus a separate key-based auth system for the SDK.

Dashboard Authentication

Email & Password

The default sign-in method. Users create an account with their name, email, and password.

Registration flow:

  1. User submits name, email, and password via /register
  2. Password is hashed with bcrypt (configurable SALT_ROUNDS, default 12)
  3. A confirmation email is sent via SendGrid containing a unique verification link
  4. User clicks the link → account is verified and fully activated
  5. User can now sign in

Sign-in flow:

  1. User submits email and password
  2. Server validates credentials and issues an RSA-signed JWT
  3. JWT is stored server-side and cross-validated on every protected request

Google Sign-In

One-click sign-in with a Google account. No password required.

Setup (self-hosted):

  1. Create OAuth 2.0 credentials at [console.cloud.google.com](https://console.cloud.google.com/) → APIs & Services → Credentials
  2. Add your dashboard URL as an authorized redirect URI (e.g. http://localhost:3001)
  3. Set in server/src/.env: 
    GOOGLE_CLIENT_ID=your_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_client_secret
  4. Set the same GOOGLE_CLIENT_ID in web-client/.env

When a user signs in with Google for the first time, a new account is created automatically using their Google profile name and email. No email confirmation is required for Google sign-ins.

Forgot Password

Users who signed up with email/password can request a reset link.

Reset flow:

  1. User submits their email at /forgot-password
  2. Server generates a time-limited reset token
  3. A password reset email is sent via SendGrid with a link valid for 24 hours
  4. User clicks the link → can set a new password

Email Notifications

tmam sends the following transactional emails via SendGrid:

Trigger Subject Content
New registration "Confirm Your Email" Verification link
Forgot password "Reset Your Password" Reset link (24h expiry)
Team invitation "You're invited to join [Org]" Invitation with role details

Configure SendGrid in server/src/.env:

SENDGRID_API_KEY=SG.xxxxxxxxxx
SENDGRID_SENDER=support@yourdomain.com
FRONTEND_URL=http://localhost:3001

If SENDGRID_API_KEY is not set, all email sending is silently skipped. This makes local development friction-free — users can still register; email confirmation is just bypassed.

SDK Authentication

The SDK does not use JWTs. Instead it authenticates using a public key / secret key pair generated in the dashboard.

  • The public key (pk-tmam-...) is sent with every SDK request as the X-Public-Key header
  • The secret key (sk-tmam-...) is sent as X-Secret-Key
  • On the server, the public key is used to look up the key record; the secret key is verified against a bcrypt hash — the plaintext secret is never stored
  • Keys are scoped to a specific organization and project

Generate keys at Settings → API Keys. See API Keys for full details.

Session Management

  • Sessions are maintained via JWT tokens stored in the database
  • Each JWT is RSA-signed (RS256) using a private key configured in server/src/.env
  • Tokens are validated on every request:
    1. The Authorization: Bearer <token> header is checked
    2. The token is looked up in the database — if not found (logged out, revoked), the request is rejected
    3. The JWT signature is verified against the RSA public key
    4. The user ID and role ID in the token are compared against the database record
  • Signing out immediately invalidates the token server-side

This means tmam does not rely on JWT expiry alone — a stolen token can be revoked instantly by signing out.

Account Verification States

State Description
isVerified: false Email not yet confirmed (email/password signup only)
isVerified: true Email confirmed or Google sign-in
isLoggedIn: true Active session with a valid token
confirmSent: true Confirmation email has been dispatched

Endpoints that require a verified account return 401 Unauthorized if the account has not confirmed its email.

Clone this wiki locally