JWT Setup

10 minutes INTERMEDIATE

Configure JWT authentication in your GEMVC application. Learn how to set up TOKEN_SECRET, configure token expiration times, and understand different token types.

What You'll Learn

Configure TOKEN_SECRET

Set up secure secret key for JWT signing

Token Expiration Times

Configure Access, Refresh, and Login token lifetimes

Token Types

Understand when to use each token type

Video Coming Soon...

What is JWT Setup?

JWT (JSON Web Token) setup in GEMVC involves configuring environment variables in your .env file. GEMVC uses these settings to create, sign, and verify JWT tokens automatically.

TOKEN_SECRET - Secret key used to sign and verify tokens (HS256 algorithm)
TOKEN_ISSUER - Identifier for your application (e.g., "MyCompany")
Token Expiration Times - Configure how long each token type remains valid

Key Point: GEMVC's JWT system is built-in - no additional packages needed! Just configure the .env file and you're ready to use JWT authentication.

Configure TOKEN_SECRET

Setting Up the Secret Key

The TOKEN_SECRET is a critical security setting. It's used to sign JWT tokens using the HS256 algorithm. Never share this secret or commit it to version control!

File Location:

Edit the .env file in your project root directory.

Add or update the TOKEN_SECRET in your .env file:

.env - TOKEN_SECRET Configuration

# JWT Configuration
TOKEN_SECRET=your-very-long-random-secret-key-here-change-this-in-production

⚠️ Security Best Practices:

✓ Use a long, random string (at least 32 characters, preferably 64+)
✓ Never use default values in production
✓ Generate a unique secret for each environment (dev, staging, production)
✓ Keep it secret - don't commit to Git or share publicly

💡 Generating a Secure Secret:

You can generate a secure random secret using PHP or command line:

Terminal

# Generate random secret (PHP)
php -r "echo bin2hex(random_bytes(32));"

# Or use OpenSSL
openssl rand -hex 32

Configure Token Expiration Times

Setting Token Lifetimes

GEMVC supports three types of tokens, each with different expiration times. Configure these in your .env file:

.env - Token Expiration Configuration

# JWT Token Expiration Times (in seconds)
ACCESS_TOKEN_VALIDATION_IN_SECONDS=300      # 5 minutes (short-lived)
REFRESH_TOKEN_VALIDATION_IN_SECONDS=3600     # 1 hour (medium-lived)
LOGIN_TOKEN_VALIDATION_IN_SECONDS=604800     # 7 days (long-lived)

Token Types Explained:

Access Token (300 seconds / 5 minutes)
Short-lived token for API requests. Use for frequent operations. Expires quickly for security.
Refresh Token (3600 seconds / 1 hour)
Medium-lived token for refreshing access tokens. Use to get new access tokens without re-login.
Login Token (604800 seconds / 7 days)
Long-lived token for "remember me" functionality. Use for persistent user sessions.

💡 Recommended Settings:

✓ Development: Longer expiration times for easier testing
✓ Production: Shorter expiration times for better security
✓ Mobile Apps: Longer login tokens (7-30 days) for better UX
✓ Web Apps: Shorter tokens (5-15 minutes) for tighter security

Configure TOKEN_ISSUER

Setting the Token Issuer

The TOKEN_ISSUER identifies your application in the JWT token. This is included in the token payload and helps identify which application issued the token.

.env - TOKEN_ISSUER Configuration

# JWT Configuration
TOKEN_ISSUER=MyCompany

Token Payload Example:

The TOKEN_ISSUER appears in the JWT token payload:

JWT Token Payload

{
    "token_id": "unique-token-id",
    "user_id": 123,
    "role": "admin,user",
    "exp": 1234567890,
    "iss": "MyCompany",    // ← This is TOKEN_ISSUER
    "type": "access"
}

Tip: Use your company name, application name, or domain name as the issuer. This helps identify tokens in multi-application environments.

Understanding Token Types

When to Use Each Token Type

GEMVC provides three token types for different use cases. Understanding when to use each type helps you build secure and user-friendly applications.

🔑 Access Token (5 minutes)

Use for: Regular API requests after login

✓ Making authenticated API calls
✓ Short-lived for security (expires quickly)
✓ Automatically refreshed using refresh token

Example: $token = (new JWTToken())->createAccessToken($userId);

🔄 Refresh Token (1 hour)

Use for: Getting new access tokens without re-login

✓ Refreshing expired access tokens
✓ Medium-lived (1 hour default)
✓ Reduces login frequency for better UX

Example: $token = (new JWTToken())->createRefreshToken($userId);

🔐 Login Token (7 days)

Use for: "Remember me" functionality and persistent sessions

✓ Long-lived sessions (7 days default)
✓ "Remember me" checkbox on login
✓ Mobile app persistent authentication

Example: $token = (new JWTToken())->createLoginToken($userId);

Complete .env Example

Full JWT Configuration

Here's a complete example of JWT configuration in your .env file:

.env - Complete JWT Configuration

# JWT Security Configuration
TOKEN_SECRET='your-very-long-random-secret-key-here-change-in-production'
TOKEN_ISSUER='MyCompany'

# Token Expiration Times (in seconds)
ACCESS_TOKEN_VALIDATION_IN_SECONDS=300      # 5 minutes
REFRESH_TOKEN_VALIDATION_IN_SECONDS=3600    # 1 hour
LOGIN_TOKEN_VALIDATION_IN_SECONDS=604800    # 7 days

# Database Configuration (for reference)
DB_HOST=localhost
DB_NAME=gemvc_db
DB_USER=root
DB_PASSWORD=yourpassword
DB_PORT=3306

# Application Settings
APP_ENV=development
QUERY_LIMIT=10

⚠️ Important Notes:

✓ Change TOKEN_SECRET to a unique, random string in production
✓ Never commit your .env file to version control
✓ Use different secrets for development, staging, and production
✓ Keep expiration times appropriate for your security requirements

Verify Your Configuration

Testing JWT Setup

After configuring your .env file, you can verify that JWT is working by creating a test token:

Quick Test:

Once you create a login endpoint (covered in the next guide), you can test JWT by:

1. Logging in with valid credentials
2. Receiving a JWT token in the response
3. Using that token in the Authorization header for protected routes

✅ Configuration Checklist:

✓ TOKEN_SECRET is set to a long, random string
✓ TOKEN_ISSUER is set to your application name
✓ Token expiration times are configured (or using defaults)
✓ .env file is not committed to Git

Important Security Notes

TOKEN_SECRET is Critical: If compromised, all tokens can be forged. Use a strong, unique secret and never share it.
Environment-Specific Secrets: Use different secrets for development, staging, and production environments.
Token Expiration: Shorter expiration times provide better security but require more frequent re-authentication.
Default Values: If expiration times are not set, GEMVC uses defaults (300s, 3600s, 604800s).

✅ JWT Setup Complete!

Great job! You've configured JWT authentication. Now let's create a login endpoint to generate and return JWT tokens to users.

Next: User Login Back to Authentication Hub Learning Hub