Understanding Trongate's Token System

Trongate comes with its own battle-tested token system for authorization and authentication.

Authentication answers "Who are you?" Authorization answers "What can you do?" Trongate handles both with tokens.

A token is a random string stored in your database. When a user logs in successfully, you generate a token. That token proves their identity on every subsequent request.

With Trongate's token system, there are no sessions to manage. No JWT overhead. No auth middleware chains. Just three database tables and some Native PHP.

The Three Security Tables

Trongate's token system uses three relational database tables. Each has a specific job:

• trongate_user_levels - Defines roles (admin, member, guest, etc.)
• trongate_users - Links users to roles
• trongate_tokens - Stores active tokens with expiry dates

Table 1: trongate_user_levels

This table defines every role in your application.

SQL Statement:

CREATE TABLE trongate_user_levels (
    id INT NOT NULL PRIMARY KEY AUTO_INCREMENT,
    level_title VARCHAR(125) NOT NULL
);

Sample data:

INSERT INTO trongate_user_levels (id, level_title) VALUES
(1, 'admin'),
(2, 'member');

That's it. One row per role. The id is what you'll reference when checking permissions.

Table 2: trongate_users

This table represents every user who needs a token.

SQL Statement:

CREATE TABLE trongate_users (
    id INT NOT NULL PRIMARY KEY AUTO_INCREMENT,
    code VARCHAR(32) NOT NULL,
    user_level_id INT(11) NOT NULL,
    FOREIGN KEY (user_level_id) REFERENCES trongate_user_levels(id)
);

Sample data:

INSERT INTO trongate_users (id, code, user_level_id) VALUES
(1, '7rSvE86mYi2Z8EKwVMrBDHm3FmTBDDkL', 1),
(2, 'Tz8tehsWsTPUHEtzfbYjXzaKNqLmfAUz', 2);

Key Points

• id - Auto-incrementing primary key. This is the "Trongate User ID" referenced throughout the system.
• code - Random 32-character string for privacy. Use this in URLs instead of exposing numeric IDs.
• user_level_id - Links to trongate_user_levels.id via foreign key.

$code = make_rand_str(32);

Table 3: trongate_tokens

This table stores active authentication tokens.

SQL Statement:

CREATE TABLE trongate_tokens (
    id INT NOT NULL PRIMARY KEY AUTO_INCREMENT,
    token VARCHAR(125) NOT NULL,
    user_id INT(11) DEFAULT 0,
    expiry_date INT(11) NOT NULL,
    code VARCHAR(3) DEFAULT '0',
    FOREIGN KEY (user_id) REFERENCES trongate_users(id)
);

Key Points

• id - Auto-incrementing primary key.
• token - The randomly generated token string (typically 32 characters).
• user_id - Links to trongate_users.id via foreign key.
• expiry_date - Unix timestamp. Tokens expire automatically.
• code - Internal use by the API manager (max 3 characters). Usually left as '0'.

When a user logs in, you insert a row here. When they log out, you delete it. Expired tokens are purged automatically.

How The Tables Connect

Here's the relationship:

trongate_tokens.user_id  →  trongate_users.id
trongate_users.user_level_id  →  trongate_user_levels.id

This means:

• Every token belongs to a user
• Every user has a level
• Query any token to instantly know the user's role

Connecting Your Application Tables

Let's say you have a members table with columns like first_name, last_name, email, and password (hashed, obviously).

To integrate with the token system:

1. Add a trongate_user_id column to your members table
2. When someone registers, create a record in both members AND trongate_users
3. Store the trongate_users.id in members.trongate_user_id

Example schema:

CREATE TABLE members (
    id INT NOT NULL PRIMARY KEY AUTO_INCREMENT,
    first_name VARCHAR(50),
    last_name VARCHAR(50),
    email VARCHAR(125) UNIQUE NOT NULL,
    password VARCHAR(60) NOT NULL,
    trongate_user_id INT(11),
    FOREIGN KEY (trongate_user_id) REFERENCES trongate_users(id)
);

Now when a member logs in:

1. Validate their email/password against the members table
2. Grab their trongate_user_id
3. Generate a token for that trongate_user_id
4. Store the token in trongate_tokens

Why This Design Works

Three tables. Clear responsibilities. No magic.

• Scalable: Add as many user types as needed without touching the token system
• Secure: Passwords live in your app tables, not framework tables
• Simple: One foreign key lookup tells you everything about a token
• Fast: Indexed queries, no complex joins required for validation

In the next section, we'll walk through exactly how tokens flow through this system from login to logout.