← Back to Home

How Authentication Works

Documentation

Auth Return uses JWT (JSON Web Tokens) for secure, stateless authentication. This page explains how tokens work, why they're secure, and how you can trust them.

What is a JWT Token?

A JWT token is a compact, URL-safe string that contains encoded information about a user. It consists of three parts separated by dots (.):

header.payload.signature

Header: Contains metadata about the token (algorithm, type)
Payload: Contains the actual data (user ID, email, expiration time)
Signature: Cryptographic signature that ensures the token hasn't been tampered with

How Tokens Are Generated

When a user successfully logs in or signs up, Auth Return generates a JWT token containing:

user_id: Unique identifier for the user
email: User's email address
iat: "Issued at" timestamp (when the token was created)
exp: Expiration timestamp (30 days from creation)

The token is then cryptographically signed using a secret key that only Auth Return knows. This signature is what makes the token secure and trustworthy.

Why Tokens Are Secure

Cryptographic Signing

Tokens are signed using the HS256 algorithm (HMAC-SHA256), which creates a cryptographic signature based on:

The token's header and payload
A secret key known only to Auth Return

If anyone tries to modify the token (e.g., change the user ID or email), the signature will no longer match, and the token will be rejected as invalid.

1. Tamper-Proof

Because tokens are cryptographically signed, any modification to the payload (user ID, email, etc.) will invalidate the signature. When a service verifies the token, it recalculates the signature and compares it to the one in the token. If they don't match, the token is rejected.

2. Expiration

Tokens expire after 30 days. This limits the window of vulnerability if a token is somehow compromised. Expired tokens cannot be used, even if they have a valid signature.

3. Stateless

Unlike session-based authentication, tokens don't require server-side storage. The token itself contains all the information needed to verify it. This makes the system more scalable and eliminates the need for a shared session store.

How We Can Trust Tokens

When a third-party service (like Bright Wrapper) receives a token, it can verify the token's authenticity by:

Checking the signature: The service sends the token to Auth Return's /api/user endpoint, which verifies the signature using the secret key.
Checking expiration: Auth Return checks if the token has expired.
Returning user info: If both checks pass, Auth Return returns the user's information (ID and email) to the service.

Important: The secret key used to sign tokens is never shared with third-party services. Only Auth Return can generate valid tokens, and only Auth Return can verify them. This means:

Third-party services cannot forge tokens
Third-party services cannot modify tokens without invalidating them
Only Auth Return can verify token authenticity

Authentication Flow

User submits login/signup form

Auth Return validates credentials

Auth Return generates JWT token (signed with secret key)

Token is returned to the user (via redirect or API response)

User's app stores token (e.g., in localStorage)

App sends token with API requests (in Authorization header or query param)

Service verifies token with Auth Return's /api/user endpoint

If valid, Auth Return returns user info; if invalid, returns error

Token Refresh

Tokens can be refreshed if they're within 7 days of expiration. This allows users to stay logged in without interruption. The refresh endpoint (/api/refresh) validates the current token and issues a new one with a fresh 30-day expiration.

Best Practices

Store tokens securely: Use localStorage or sessionStorage in the browser, or secure storage in mobile apps.
Send tokens securely: Always use HTTPS when transmitting tokens.
Validate tokens: Always verify tokens with Auth Return's API before trusting user identity.
Handle expiration: Check for token expiration and prompt users to re-authenticate or refresh their tokens.

API Endpoints

POST /api/login - Login and receive a token
POST /api/signup - Sign up and receive a token
GET /api/user?token=... - Verify token and get user info
POST /api/refresh - Refresh an expiring token
GET /api/verify?token=... - Verify token validity

For technical implementation details, see the API documentation.