CodeIgniter 4 REST API with JWT authentication, ready for your mobile & frontend team

Not a tutorial that stops at "token created". The CI4 Starter Kit ships a complete REST API: JWT login, rotating refresh tokens, per-endpoint permissions shared with the web app, Swagger docs, and a Postman collection.

One-time payment · unlimited projects · In Indonesia? Lynk.id QRIS/VA

The real thing

Click a screenshot to enlarge it. The full demo video is on the main page.

The parts JWT tutorials usually skip

Most CodeIgniter 4 REST API JWT authentication tutorials stop once a token is issued at login. In a real project that's where the questions start: when does the token expire, how do you renew it without logging in again, how do you revoke it on logout, and how do you restrict endpoints by role?

This kit answers all of them. The API also uses the same roles & permissions matrix as the admin panel, so access rules are never defined twice.

JWT auth done properly

  • Short-lived access tokens (15 minutes by default)
  • Single-use refresh tokens, rotated on every use (14 days by default)
  • Refresh tokens stored hashed, revoked on logout
  • Login with username or email, 2FA supported

Per-endpoint permissions from RBAC

  • API routes protected by the jwt + permission filters
  • GET needs Read, POST Create, PUT/PATCH Update, DELETE Delete
  • Same roles matrix as the web app
  • Per user: web only, API only, or both

Docs & tooling

  • OpenAPI 3 (openapi.yaml) + Swagger UI inside the app
  • Postman collection ready to import
  • CORS ready for SPAs (React, Vue, etc.)
  • Consistent response envelope: success, message, data

Built-in protection & tests

  • Per-IP rate limiting on login & refresh
  • Temporary account lockout (HTTP 429) after repeated failures
  • API sign-ins recorded in the audit log
  • PHPUnit tests for the API and the JWT service

The flow, from login to token refresh

Every example below can be run straight from the bundled Swagger UI or Postman collection.

  1. Log in and get a token pair

    login accepts a username or an email. If the account uses 2FA, send otp as well.

    curl -X POST https://your-app.test/api/auth/login \
      -H "Content-Type: application/json" \
      -d '{"login":"admin","password":"Password123"}'
    
    {
      "success": true,
      "message": "Login successful.",
      "data": {
        "access_token": "eyJhbGciOi...",
        "token_type": "Bearer",
        "expires_in": 900,
        "refresh_token": "…",
        "refresh_expires_in": 1209600
      }
    }
  2. Call endpoints with the Bearer token

    Each endpoint checks the user's role permissions. Without the Delete flag, for example, a DELETE is rejected.

    curl https://your-app.test/api/products \
      -H "Authorization: Bearer eyJhbGciOi..."
  3. On a 401, exchange the refresh token

    A refresh token works only once. The response contains a fresh token pair.

    curl -X POST https://your-app.test/api/auth/refresh \
      -H "Content-Type: application/json" \
      -d '{"refresh_token":"…"}'
  4. Add your own endpoints

    Put the route in the jwt group, give it a permission, and copy the Products example controller.

    $routes->group('', ['filter' => 'jwt'], static function ($routes) use ($p) {
        $routes->get('invoices', 'Invoices::index', $p('invoices'));
        $routes->delete('invoices/(:num)', 'Invoices::delete/$1', $p('invoices', 'delete'));
    });

A typical JWT tutorial vs the CI4 Starter Kit

FeatureJWT tutorialCI4 Starter Kit
Login returns a token✓ Yes✓ Yes
Refresh tokens + rotationRarely✓ Yes
Logout revokes the token✕ No✓ Yes
Role-based permission per endpoint✕ NoShared with web
2FA, rate limit & lockout on login✕ No✓ Yes
Swagger / OpenAPI✕ No✓ Yes
Postman collection + CORSSometimes✓ Yes
PHPUnit tests✕ No✓ Yes

Buy now on Gumroad

Common questions

Which JWT library does it use?

firebase/php-jwt, the most widely used PHP JWT library, with HS256. The secret must be set in .env (at least 32 characters), and access & refresh token lifetimes are configurable in app/Config/Auth.php.

Does it work with Flutter, React, or Vue apps?

Yes. The API returns JSON in a consistent envelope and CORS is set up for SPAs. Your app stores the access and refresh tokens and calls /api/auth/refresh when it gets an HTTP 401.

Why refresh tokens instead of one long-lived token?

A leaked access token is only valid briefly (15 minutes by default). Refresh tokens are stored hashed, work only once, and are revoked on logout, so a session can be cut off at any time.

Do I have to use the web admin panel too?

No. Each user can be web only, API only, or both. Roles and permissions are still managed in the admin panel, so you don't have to build a permissions UI yourself.