The Complete Token Lifecycle

Trongate's token system follows a simple, predictable flow. No hidden state. No magic middleware. Just explicit steps that you control. This page explains exactly how the token system operates for authentication and authorization.

Here's what happens from login to logout:

1. User logs in - They submit credentials (username/password, email/password, etc.)
2. You validate credentials - Check against YOUR database table (e.g., members, administrators)
3. Token gets generated - A random 32-character string is created
4. Token gets stored in database - Insert into trongate_tokens with user_id and expiry_date
5. Token gets stored on device - Save in session or cookie
6. User makes subsequent requests - Token is sent automatically with each request
7. Token gets validated - Check database: does it exist? Has it expired? Does user have required level?
8. Access granted or denied - If valid, proceed. If not, redirect to login
9. Token expires or gets destroyed - Either reaches expiry_date or user logs out

What Trongate Does (and Doesn't Do)

Trongate's token system is managed via a module, that's included with the framework, named 'Trongate Tokens'.

The Trongate Tokens module is responsible for:

• Generating tokens
• Storing tokens
• Validating tokens
• Destroying tokens

That's all.

The Trongate Tokens module is not responsible for:

• How users log in
• How you manage the login process
• Any kind of rate limiting
• Restricting how many users are allowed to be logged in

Once you've decided a user is legitimate, THEN you call Trongate to generate a token.

This separation is intentional. It keeps the token system simple, flexible, and future-proof.

Example: Members-Only Website

Let's walk through a concrete example. You're building a members-only website.

Setup Phase

First, create your database tables:

Add a "member" user level:

Registration Phase

When someone registers:

Login Phase

When someone logs in:

Protected Page Phase

On any members-only page:

Logout Phase

Token Storage Locations

When you generate a token, it gets stored in TWO places:

1. Database - Always stored in trongate_tokens table
2. User's device - Stored as either a session variable OR a cookie

Storage Option 1: Session (Default)

Use case: Standard web applications. Token persists until browser closes or session expires.

Storage Option 2: Cookie

Use case: "Remember me" functionality. Token persists across browser sessions.

Token Validation Priority

When validating tokens, Trongate checks two locations in this order:

1. Cookies - $_COOKIE['trongatetoken']
2. Session - $_SESSION['trongatetoken']

The first valid token found wins.

Token Expiration

Every token has an expiry_date stored as a Unix timestamp.

Default lifespan: 86400 seconds (24 hours)

When validating tokens, Trongate automatically checks:

Expired tokens return false during validation, forcing re-authentication.

The Trongate Security Module

Trongate includes a Trongate_security module that provides a centralized way to handle authorization checks across your application.

Instead of calling trongate_tokens methods directly, you can use:

The Trongate_security module uses scenario-based access control, making it easy to define different authorization rules for different parts of your application (admin panel, members area, etc.).

Security Considerations

A few important points:

• Tokens are NOT encrypted - They're random strings. Treat them like passwords.
• Always use HTTPS - Tokens sent over HTTP can be intercepted.
• Hash passwords properly - Use password_hash() and password_verify(). Never store plain text.
• Set appropriate expiry dates - Short-lived tokens for sensitive operations, longer for convenience.
• Clean up on user deletion - When deleting a user, delete their tokens too using delete_old_tokens().

Database Requirements

Trongate's token system requires a MySQL or MariaDB database.

The system is database-driven by design. Every token validation queries the trongate_tokens table to check:

• Does the token exist?
• Has it expired?
• What user level does it have?

This approach ensures tokens can be invalidated instantly (e.g., when a user logs out or gets banned) without waiting for session timeouts.

What's Next

Now that you understand the workflow, the next pages will show you exactly how to:

• Generate tokens with the trongate_tokens module
• Validate tokens and fetch user data
• Destroy tokens on logout

Each page includes working code examples you can copy directly into your application.