Authentication Quick Reference Card

Last Updated: October 22, 2025 Full Guide: AUTHENTICATION.md

Config Values (MUST BE EXACT!)

// In config/api.php

'auth_method' => 'apikey',  // ? Correct (NOT 'api_key')
'auth_method' => 'basic',   // ? Correct
'auth_method' => 'jwt',     // ? Correct
'auth_method' => 'oauth',   // ? Correct (placeholder)

API Key Authentication

Config:

'auth_method' => 'apikey',
'api_keys' => ['changeme123'],
'api_key_role' => 'admin',  // Role for all API key users

Usage:

# Header (recommended)
curl -H "X-API-Key: changeme123" http://localhost:8000?action=tables

# Query parameter
curl "http://localhost:8000?action=tables&api_key=changeme123"

Basic Authentication

Config:

'auth_method' => 'basic',
'basic_users' => [
    'admin' => 'secret',
],
'user_roles' => [
    'admin' => 'admin',
],
'use_database_auth' => true,  // Check database too

Usage:

# cURL
curl -u admin:secret http://localhost:8000?action=tables

# JavaScript
const credentials = btoa('admin:secret');
fetch('/api.php?action=tables', {
  headers: { 'Authorization': 'Basic ' + credentials }
});

Create Database User:

php scripts/create_user.php john john@email.com SecurePass123! readonly

JWT Authentication

Config:

'auth_method' => 'jwt',
'jwt_secret' => 'a7f92c8e4b6d1f3a9e8c7b5d2f1a6e9b...',  // Change this!
'jwt_expiration' => 3600,  // 1 hour
'use_database_auth' => true,

Step 1 - Login:

curl -X POST \
  -d "username=john&password=SecurePass123!" \
  http://localhost:8000?action=login

# Response:
# {"success":true,"token":"eyJ0eXAi...","expires_in":3600,"user":"john","role":"readonly"}

Step 2 - Use Token:

curl -H "Authorization: Bearer eyJ0eXAi..." \
  http://localhost:8000?action=tables

JavaScript Example:

// Login
const loginRes = await fetch('/api.php?action=login', {
  method: 'POST',
  body: new URLSearchParams({
    username: 'john',
    password: 'SecurePass123!'
  })
});
const { token } = await loginRes.json();

// Use token
const dataRes = await fetch('/api.php?action=tables', {
  headers: { 'Authorization': 'Bearer ' + token }
});
const data = await dataRes.json();

RBAC Roles

Predefined Roles:

| Role | Tables | Actions | System Tables | |------|--------|---------|---------------| | admin | All (*) | All | ? Can access | | readonly | All (*) | list, read | ? Blocked | | editor | All (*) | All | ? Blocked | | users_manager | users, orders | Specific | ? No access |

Config:

'roles' => [
    'admin' => [
        '*' => ['list', 'read', 'create', 'update', 'delete']
    ],
    'readonly' => [
        '*' => ['list', 'read'],
        'api_users' => [],       // Empty array = DENY
        'api_key_usage' => [],
    ],
],

Actions: - list - View list - read - View single record - create - Insert - update - Modify - delete - Remove

Role Assignment by Auth Method

| Auth Method | Role Source | |-------------|-------------| | apikey | api_key_role in config | | basic (config users) | user_roles mapping | | basic (DB users) | api_users.role column | | jwt | role claim in token |

Common Issues

"401 Unauthorized"

• Check `auth_method` matches your usage
• Verify credentials/token
• Ensure `auth_enabled = true`

"403 Forbidden: No role assigned"

• API Key: Add `'api_key_role' => 'admin'` to config
• Basic Auth: Add user to `user_roles` mapping or check DB role
• JWT: Role should be in token claims

"403 Forbidden" (with role)

• Check RBAC permissions for your role
• System tables blocked for non-admin roles

API Key doesn't work

• Use `'apikey'` NOT `'api_key'` (no underscore!)

Performance Comparison

| Method | DB Queries per Request | Best For | |--------|------------------------|----------| | API Key | 0 | Webhooks | | Basic (config) | 0 | Development | | Basic (DB) | 1 | Small apps | | JWT | 0 | Production |

JWT Performance: - Before: 600,000 auth queries/hour - After: 1,000 auth queries/hour - Reduction: 99.8% ?

Security Checklist

• [ ] Use HTTPS in production
• [ ] Change `jwt_secret` to random 64+ char string
• [ ] Rotate API keys every 90 days
• [ ] Use strong passwords (8+ chars, mixed case, numbers, symbols)
• [ ] Enable rate limiting (`'rate_limit' => ['enabled' => true]`)
• [ ] Monitor authentication failures (dashboard)
• [ ] Set appropriate JWT expiration (1-24 hours)
• [ ] Block system tables for non-admin roles
• [ ] Use database users (not config file) for production

Quick Commands

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

# Create database user
php scripts/create_user.php <username> <email> <password> <role>

# Test authentication
curl -H "X-API-Key: changeme123" http://localhost:8000?action=tables

# View monitoring dashboard
# http://localhost/PHP-CRUD-API-Generator/dashboard.html

Documentation Links

• AUTHENTICATION.md - Complete guide (50+ pages)
• USER_MANAGEMENT.md - User management system
• QUICK_START_USERS.md - 5-minute setup
• SECURITY_RBAC_TESTS.md - RBAC testing
• PERFORMANCE_AUTHENTICATION.md - Performance optimization

Need help? Read the full guide: docs/AUTHENTICATION.md