PHPackages                             rluders/jwtauth - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. rluders/jwtauth

ActiveWinter-plugin[Authentication & Authorization](/categories/authentication)

rluders/jwtauth
===============

JSON Web Token Authentication plugin for Winter CMS

v2.0.2(1mo ago)3080329[6 issues](https://github.com/rluders/wn-jwtauth-plugin/issues)[3 PRs](https://github.com/rluders/wn-jwtauth-plugin/pulls)GPL-3.0-or-laterPHPPHP >=8.1CI passing

Since Aug 18Pushed 1mo ago3 watchersCompare

[ Source](https://github.com/rluders/wn-jwtauth-plugin)[ Packagist](https://packagist.org/packages/rluders/jwtauth)[ Docs](http://www.luders.com.br)[ GitHub Sponsors](https://github.com/rluders)[ Patreon](https://www.patreon.com/rluders)[ RSS](/packages/rluders-jwtauth/feed)WikiDiscussions main Synced today

READMEChangelog (5)Dependencies (6)Versions (25)Used By (0)

 [![](jwt.png)](jwt.png)

 [ ![](https://camo.githubusercontent.com/75384fb9319afde1bafb669a1a4f593434c00fca811d41d5e764c1b12d08a283/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f57696e746572253230434d532d506c7567696e2d2532334545373230332e737667) ](https://wintercms.com/plugin/rluders-jwtauth) [ ![](https://github.com/rluders/wn-jwtauth-plugin/actions/workflows/test.yml/badge.svg) ](https://github.com/rluders/wn-jwtauth-plugin/actions/workflows/test.yml) [ ![](https://camo.githubusercontent.com/1576df4d95a30b61fed99d6564293daaedbbd481434a8aeeb26617a9ac22d8cd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f537570706f72745f6f6e2d50617472656f6e2d677265656e2e737667) ](https://www.patreon.com/rluders) [ ![](https://camo.githubusercontent.com/85ceab570869e49f30edc6d9299bc137a463b41d254cc640f48ad90b95cc2f91/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f726c75646572732f6f632d6a7774617574682d706c7567696e2e737667) ](https://www.gnu.org/licenses/gpl-3.0.en.html)

Introduction
============

[](#introduction)

This plugin provides a JSON Web Tokens authentication mechanism for [Winter CMS](http://www.wintercms.com) integrated with `Winter.User`. It's essential for your web application built with Angular, Vue.js, React or other modern Javascript frameworks.

Requirements
------------

[](#requirements)

- PHP 8.1+
- WinterCMS 1.2+ (Laravel 9) or 1.3+ (Laravel 10)
- [Winter.User](https://github.com/wintercms/wn-user-plugin) plugin `^2.0`
- [RLuders.CORS](https://wintercms.com/plugin/rluders-cors) plugin (optional, but recommended)

Theme
-----

[](#theme)

- [Angular Skeleton](https://wintercms.com/theme/rluders-angular2)

Tutorials
---------

[](#tutorials)

- [Creating Vue, Vuex and Winter CMS APP - Login and Register](https://www.youtube.com/watch?v=8S3DySmMOuk) by [Watch and Learn](https://www.youtube.com/channel/UCXQC_GB5hG6PkzIhSMZ-hWA)

Installation
============

[](#installation)

```
$ composer require rluders/jwtauth
```

Configuration
=============

[](#configuration)

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

Usage
=====

[](#usage)

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

> If you are using [**Postman**](https://www.getpostman.com/), you can [click here to import the collection](https://www.getpostman.com/collections/5667c055f6f81ff3f821) with all the calls that you need to test it.

Login
-----

[](#login)

`POST /api/auth/login`

**Route name**

`api.auth.login`

### Parameters

[](#parameters)

NameTypeRequiredDescriptionloginstringYesAccount login attributepasswordstringYesAccount 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

[](#responses)

**SUCCESS**

> Code: 200

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

**ERROR**

> Code: 401

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

Register
--------

[](#register)

`POST /api/auth/register`

**Route name**

`api.auth.register`

### Parameters

[](#parameters-1)

NameTypeRequiredDescriptionusernamestringNoAccount usernameemailstringYesAccount emailpasswordstringYesAccount passwordpassword\_confirmationstringNoConfirm the new password> The field `username` can be **required**. It depends of your `Winter.User` configuration.

### Responses

[](#responses-1)

**SUCCESS**

> Code: 201

```
[]
```

**ERROR**

> Code: 401

```
{
  "error": object | registration_disabled
}
```

### Supported events

[](#supported-events)

- `Winter.User.beforeRegister`
- `Winter.User.register`

Account Activation
------------------

[](#account-activation)

`POST /api/auth/account-activation`

**Route name**

`api.auth.account-activation`

### Parameters

[](#parameters-2)

NameTypeRequiredDescriptionactivation\_codestringYesAccount activation code### Responses

[](#responses-2)

**SUCCESS**

> Code: 200

```
[]
```

**ERROR**

> Code: 422

```
{
  "error": invalid_activation_code | invalid_user | user_not_found
}
```

Forgot Password
---------------

[](#forgot-password)

`POST /api/auth/forgot-password`

**Route name**

`api.auth.forgot-password`

### Parameters

[](#parameters-3)

NameTypeRequiredDescriptionemailstringYesAccount email### Responses

[](#responses-3)

**SUCCESS**

> Code: 200

```
[]
```

**ERROR**

> Code: 404

```
{
  "error": user_not_found
}
```

Reset Password
--------------

[](#reset-password)

`POST /api/auth/reset-password`

**Route name**

`api.auth.reset-password`

### Parameters

[](#parameters-4)

NameTypeRequiredDescriptionreset\_password\_codestringYesReset password codepasswordstringYesAccount new passwordpassword\_confirmationstringNoConfirm the new password### Responses

[](#responses-4)

**SUCCESS**

> Code: 200

```
[]
```

**ERROR**

> Code: 422

```
{
  "error":
    invalid_reset_password_code | invalid_user | invalid_reset_password_code
}
```

Refresh Token
-------------

[](#refresh-token)

`POST /api/auth/refresh-token`

**Route name**

`auth.api.refresh-token`

### Parameters

[](#parameters-5)

NameTypeRequiredDescriptiontokenstringYesValid user JWToken### Responses

[](#responses-5)

**SUCCESS**

> Code: 200

```
{
  "token": string
}
```

**ERROR**

> Code: 403

```
{
  "error": could_not_refresh_token | given_token_was_blacklisted
}
```

Get User
--------

[](#get-user)

`GET /api/auth/me`

**Middleware**

`jwt.auth`

**Route name**

`api.auth.me`

### Parameters

[](#parameters-6)

NameTypeRequiredDescriptiontokenstringYesValid token### Responses

[](#responses-6)

**SUCCESS**

> Code: 200

```
{
  "user": object
}
```

**ERROR**

> Code: 404

```
{
  "error": user_not_found
}
```

Logout
------

[](#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

[](#responses-7)

**SUCCESS**

> Code: 204 No Content

**ERROR**

> Code: 401 — Missing or invalid token

---

Advanced
========

[](#advanced)

Custom JWT Claims
-----------------

[](#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
----------------------

[](#openapi--swagger-spec)

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

Testing
-------

[](#testing)

Requires [Podman](https://podman.io/) 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](CONTRIBUTING.md) for the commit convention and PR workflow.

---

Known issues
============

[](#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
--------------------

[](#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
=======

[](#license)

GPLv3

###  Health Score

59

—

FairBetter than 98% of packages

Maintenance88

Actively maintained with recent releases

Popularity30

Limited adoption so far

Community24

Small or concentrated contributor base

Maturity81

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 63.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~177 days

Recently: every ~486 days

Total

17

Last Release

39d ago

Major Versions

v1.5.0 → v2.0.02026-05-24

PHP version history (3 changes)v1.2.2PHP >=7.0

v1.4.2PHP >=7.2

v2.0.0PHP >=8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/094cc4b75064dd5b8b40bafde99c5e35d7d978eb26f5bbf0613b4c5993b935a8?d=identicon)[rluders](/maintainers/rluders)

---

Top Contributors

[![rluders](https://avatars.githubusercontent.com/u/191027?v=4)](https://github.com/rluders "rluders (65 commits)")[![Incremental92](https://avatars.githubusercontent.com/u/63950081?v=4)](https://github.com/Incremental92 "Incremental92 (7 commits)")[![josephcrowell](https://avatars.githubusercontent.com/u/2770395?v=4)](https://github.com/josephcrowell "josephcrowell (7 commits)")[![khorashadi666](https://avatars.githubusercontent.com/u/43370342?v=4)](https://github.com/khorashadi666 "khorashadi666 (4 commits)")[![bkrajendra](https://avatars.githubusercontent.com/u/994083?v=4)](https://github.com/bkrajendra "bkrajendra (4 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (3 commits)")[![cch504](https://avatars.githubusercontent.com/u/30062429?v=4)](https://github.com/cch504 "cch504 (2 commits)")[![bernardotavares](https://avatars.githubusercontent.com/u/25110465?v=4)](https://github.com/bernardotavares "bernardotavares (2 commits)")[![vittoboa](https://avatars.githubusercontent.com/u/38300176?v=4)](https://github.com/vittoboa "vittoboa (1 commits)")[![Athov](https://avatars.githubusercontent.com/u/8526043?v=4)](https://github.com/Athov "Athov (1 commits)")[![boxybird](https://avatars.githubusercontent.com/u/18317878?v=4)](https://github.com/boxybird "boxybird (1 commits)")[![bugzbrown](https://avatars.githubusercontent.com/u/190893?v=4)](https://github.com/bugzbrown "bugzbrown (1 commits)")[![Dinver](https://avatars.githubusercontent.com/u/36528841?v=4)](https://github.com/Dinver "Dinver (1 commits)")[![omid-mamandi](https://avatars.githubusercontent.com/u/109524457?v=4)](https://github.com/omid-mamandi "omid-mamandi (1 commits)")[![Su5eD](https://avatars.githubusercontent.com/u/51261569?v=4)](https://github.com/Su5eD "Su5eD (1 commits)")[![anotterdev](https://avatars.githubusercontent.com/u/18031711?v=4)](https://github.com/anotterdev "anotterdev (1 commits)")

---

Tags

hacktoberfestjwtjwt-authenticationjwtauthtokentoken-authenticationwintercmswintercms-pluginjwtjsonapiAuthenticationcmswinterwintercmsWeb Token

### Embed Badge

![Health badge](/badges/rluders-jwtauth/health.svg)

```
[![Health](https://phpackages.com/badges/rluders-jwtauth/health.svg)](https://phpackages.com/packages/rluders-jwtauth)
```

###  Alternatives

[auth0/auth0-php

PHP SDK for Auth0 Authentication and Management APIs.

41021.9M91](/packages/auth0-auth0-php)[auth0/login

Auth0 Laravel SDK. Straight-forward and tested methods for implementing authentication, and accessing Auth0's Management API endpoints.

2795.3M3](/packages/auth0-login)[rbdwllr/reallysimplejwt

A really simple library to generate user authentication JSON Web Tokens.

2902.5M23](/packages/rbdwllr-reallysimplejwt)[auth0/symfony

Symfony SDK for Auth0 Authentication and Management APIs.

128814.6k](/packages/auth0-symfony)[helsingborg-stad/municipio

A bootstrap theme for creating municipality sites.

4028.5k10](/packages/helsingborg-stad-municipio)[winter/wn-user-plugin

User plugin for Winter CMS

1338.6k17](/packages/winter-wn-user-plugin)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)