rluders/jwtauth

JSON Web Token Authentication plugin for Winter CMS

v2.0.2 2026-05-24 21:56 UTC

Requires

• php: >=8.1
• php-open-source-saver/jwt-auth: ^2.2
• winter/wn-user-plugin: ^2.0

Requires (Dev)

• mockery/mockery: ^1.6

GPL-3.0-or-later

• Ricardo Lüders

• json
• api
• Authentication
• cms
• jwt
• Web Token
• winter
• wintercms

README

Introduction

This plugin provides a JSON Web Tokens authentication mechanism for Winter CMS integrated with Winter.User. It's essential for your web application built with Angular, Vue.js, React or other modern Javascript frameworks.

Requirements

• PHP 8.1+
• WinterCMS 1.2+ (Laravel 9) or 1.3+ (Laravel 10)
• Winter.User plugin ^2.0
• RLuders.CORS plugin (optional, but recommended)

Theme

• Angular Skeleton

Tutorials

• Creating Vue, Vuex and Winter CMS APP - Login and Register by Watch and Learn

Installation

$ composer require rluders/jwtauth

Configuration

You must set a secret token for your application. Do do it, on Winter's Backend access: Settings > Users > JWTAuth

Usage

Here's the list of available endpoints for this plugin.

If you are using Postman, you can click here to import the collection with all the calls that you need to test it.

Login

POST /api/auth/login

Route name

api.auth.login

Parameters

Name	Type	Required	Description
login	string	Yes	Account login attribute
password	string	Yes	Account password

The field login value can be the account email or username. You can select it on Winter.User configuration what field should be used for login.

Responses

SUCCESS

Code: 200

{
  "token": string,
  "user": object
}

ERROR

Code: 401

{
  "error":
    invalid_credentials |
    could_not_create_token |
    user_inactive |
    user_is_banned
}

Register

POST /api/auth/register

Route name

api.auth.register

Parameters

Name	Type	Required	Description
username	string	No	Account username
email	string	Yes	Account email
password	string	Yes	Account password
password_confirmation	string	No	Confirm the new password

The field username can be required. It depends of your Winter.User configuration.

Responses

SUCCESS

Code: 201

[]

ERROR

Code: 401

{
  "error": object | registration_disabled
}

Supported events

• Winter.User.beforeRegister
• Winter.User.register

Account Activation

POST /api/auth/account-activation

Route name

api.auth.account-activation

Parameters

Name	Type	Required	Description
activation_code	string	Yes	Account activation code

Responses

SUCCESS

Code: 200

[]

ERROR

Code: 422

{
  "error": invalid_activation_code | invalid_user | user_not_found
}

Forgot Password

POST /api/auth/forgot-password

Route name

api.auth.forgot-password

Parameters

Name	Type	Required	Description
email	string	Yes	Account email

Responses

SUCCESS

Code: 200

[]

ERROR

Code: 404

{
  "error": user_not_found
}

Reset Password

POST /api/auth/reset-password

Route name

api.auth.reset-password

Parameters

Name	Type	Required	Description
reset_password_code	string	Yes	Reset password code
password	string	Yes	Account new password
password_confirmation	string	No	Confirm the new password

Responses

SUCCESS

Code: 200

[]

ERROR

Code: 422

{
  "error":
    invalid_reset_password_code | invalid_user | invalid_reset_password_code
}

Refresh Token

POST /api/auth/refresh-token

Route name

auth.api.refresh-token

Parameters

Name	Type	Required	Description
token	string	Yes	Valid user JWToken

Responses

SUCCESS

Code: 200

{
  "token": string
}

ERROR

Code: 403

{
  "error": could_not_refresh_token | given_token_was_blacklisted
}

Get User

GET /api/auth/me

Middleware

jwt.auth

Route name

api.auth.me

Parameters

Name	Type	Required	Description
token	string	Yes	Valid token

Responses

SUCCESS

Code: 200

{
  "user": object
}

ERROR

Code: 404

{
  "error": user_not_found
}

Logout

POST /api/auth/logout

Middleware

jwt.auth

Route name

api.auth.logout

Invalidates (blacklists) the current JWT. The token cannot be used again.

Responses

SUCCESS

Code: 204 No Content

ERROR

Code: 401 — Missing or invalid token

Advanced

Custom JWT Claims

Other plugins can add custom claims to the JWT by listening to the rluders.jwtauth.customClaims event. The listener receives (&$claims, $user) — modify the $claims array by reference.

// In another plugin's boot() method
Event::listen('rluders.jwtauth.customClaims', function (&$claims, $user) {
    $claims['role'] = $user->role;
    $claims['org']  = $user->organisation_id;
});

OpenAPI / Swagger Spec

A machine-readable API spec is available at openapi.yaml. Import it into Postman, Insomnia, Swagger UI, or any OpenAPI-compatible tooling.

Testing

Requires Podman or Docker.

# Build test image and run the full test suite
make test

# Unit tests only
make test-unit

# Feature tests only
make test-feature

# Drop into the container shell for debugging
make shell

See CONTRIBUTING.md for the commit convention and PR workflow.

Known issues

Beside the fact that I'm always trying to solve the possible issues, bad things could happen. Here, an list of possible issues and how to fix it.

Note to Apache users

In order to use the authorization Bearer Token you must add the following code to your .httaccess

RewriteEngine On
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]

License

GPLv3