Skip to content
AuthStack Docs

Concepts

This guide explains the fundamental concepts behind AuthStack.

Authentication Flow

Section titled “Authentication Flow”

AuthStack uses a token-based authentication system:

  1. User provides credentials (email/password or OAuth)
  2. Server validates credentials
  3. Server issues access token and refresh token
  4. Client stores tokens securely
  5. Client includes access token in API requests
  6. When access token expires, use refresh token to get a new one

Tokens

Section titled “Tokens”

Access Token

Section titled “Access Token”
  • Short-lived JWT (default: 60 minutes)
  • Contains user claims (id, email, roles)
  • Sent with every authenticated request
  • Should not be stored in localStorage (use memory or secure storage)

Refresh Token

Section titled “Refresh Token”
  • Long-lived token (default: 30 days)
  • Used only to obtain new access tokens
  • Stored securely (HttpOnly cookie or secure storage)
  • Revoked on logout or security events

JWT Structure

Section titled “JWT Structure”

Access tokens are JSON Web Tokens with this structure:

{
  "sub": "user-id",
  "email": "user@example.com",
  "name": "User Name",
  "roles": ["user"],
  "iat": 1234567890,
  "exp": 1234571490,
  "iss": "AuthStack",
  "aud": "AuthStackApps"
}

OAuth Providers

Section titled “OAuth Providers”

AuthStack supports these OAuth providers:

  • Google - Sign in with Google accounts
  • More providers coming soon

User Management

Section titled “User Management”

Users have the following properties:

  • id - Unique identifier
  • email - Email address (unique)
  • firstName / lastName - Name
  • avatarUrl - Profile picture URL
  • googleId - Linked Google account (if any)
  • emailVerified - Email verification status
  • isActive - Account status

Security Best Practices

Section titled “Security Best Practices”
  1. Never store access tokens in localStorage
  2. Use HTTPS for all API calls
  3. Implement token refresh before expiration
  4. Handle token revocation gracefully
  5. Validate tokens on the server side

Next Steps

Section titled “Next Steps”