PHP Open Source Saver JWT Auth

https://github.com/php-open-source-saver/jwt-auth
Admin
A maintained fork of JWT authentication library for Laravel that provides JSON Web Token support...
Tokens:39,331
Snippets:314
Trust Score:5.2
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Login endpoint response example

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/quick-start.md

Example JSON response from POSTing to the login endpoint with valid credentials. Contains access_token, token_type, and expires_in fields.

```json
{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
    "token_type": "bearer",
    "expires_in": 3600
}
```

--------------------------------

### Install jwt-auth via Composer

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/laravel-installation.md

Installs the latest version of the jwt-auth package via Composer.

```bash
composer require php-open-source-saver/jwt-auth
```

--------------------------------

### Log in a user and get a JWT with auth()->login()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Log in a user and return a JWT for them using auth()->login().

```php
// Get some user from somewhere
$user = User::first();

// Get the token
$token = auth()->login($user);
```

--------------------------------

### Get user or throw exception with auth()->userOrFail()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Get the authenticated user or throw a UserNotDefinedException if the user is not set.

```php
try {
    $user = auth()->userOrFail();
} catch (\PHPOpenSourceSaver\JWTAuth\Exceptions\UserNotDefinedException $e) {
    // do something
}
```

--------------------------------

### Set request instance with auth()->setRequest()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Set the request instance explicitly and then get the user.

```php
$user = auth()->setRequest($request)->user();
```

--------------------------------

### Set token explicitly with auth()->setToken()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Set the token explicitly and then get the user.

```php
$user = auth()->setToken('eyJhb...')->user();
```

--------------------------------

### Get token by user ID with auth()->tokenById()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Get a token based on a given user's id.

```php
$token = auth()->tokenById(123);
```

--------------------------------

### Get the authenticated user with auth()->user()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Get the currently authenticated user. Returns null if the user is not authenticated.

```php
// Get the currently authenticated user
$user = auth()->user();
```

--------------------------------

### Get JWT payload with auth()->payload()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Get the raw JWT payload and access claims directly using methods like get(), array access, or toArray().

```php
$payload = auth()->payload();

// then you can access the claims directly e.g.
$payload->get('sub'); // = 123
$payload['jti']; // = 'asfe4fq434asdf'
$payload('exp') // = 123456
$payload->toArray(); // = ['sub' => 123, 'exp' => 123456, 'jti' => 'asfe4fq434asdf'] etc
```

--------------------------------

### payload()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Get the raw JWT payload.

```APIDOC
## payload()

### Description
Get the raw JWT payload.

### Method
payload

### Request Example
```php
$payload = auth()->payload();
```

### Response
- **object** - The JWT payload object.

### Response Example
```php
$payload->get('sub'); // = 123
$payload['jti']; // = 'asfe4fq434asdf'
$payload('exp') // = 123456
$payload->toArray(); // = ['sub' => 123, 'exp' => 123456, 'jti' => 'asfe4fq434asdf'] etc
```
```

--------------------------------

### userOrFail()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Get the currently authenticated user or throw an exception if not authenticated.

```APIDOC
## userOrFail()

### Description
Get the currently authenticated user or throw an exception if not authenticated.

### Method
userOrFail

### Request Example
```php
try {
    $user = auth()->userOrFail();
} catch (\PHPOpenSourceSaver\JWTAuth\Exceptions\UserNotDefinedException $e) {
    // do something
}
```

### Response
- **object** - The authenticated user.

### Exceptions
- **\PHPOpenSourceSaver\JWTAuth\Exceptions\UserNotDefinedException** - Thrown if the user is not set.
```

--------------------------------

### user()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Get the currently authenticated user. Returns null if not authenticated.

```APIDOC
## user()

### Description
Get the currently authenticated user. Returns null if not authenticated.

### Method
user

### Request Example
```php
$user = auth()->user();
```

### Response
- **object|null** - The authenticated user or null.

### Response Example
```php
$user = User::first();
```
```

--------------------------------

### tokenById()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Get a token based on a given user's id.

```APIDOC
## tokenById()

### Description
Get a token based on a given user's id.

### Method
tokenById

### Parameters
- **$id** (int) - Required - The user's id.

### Request Example
```php
$token = auth()->tokenById(123);
```

### Response
- **string** - The JWT token.

### Response Example
```php
$token = 'eyJhb...';
```
```

--------------------------------

### Override token TTL with auth()->setTTL()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Override the token TTL. This example sets the token to expire after 2 hours (120 minutes).

```php
$token = auth()->setTTL(120)->attempt($credentials);
```

--------------------------------

### Create AuthController via artisan

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/quick-start.md

Artisan command to create the AuthController. Run this before adding the controller code.

```bash
php artisan make:controller AuthController
```

--------------------------------

### Create AuthController with JWT methods

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/quick-start.md

Full AuthController with login, me, logout, refresh, and respondWithToken methods. Uses auth:api middleware except for login. Returns JSON responses with token details.

```php
<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Auth;
use App\Http\Controllers\Controller;

class AuthController extends Controller
{
    /**
     * Create a new AuthController instance.
     *
     * @return void
     */
    public function __construct()
    {
        $this->middleware('auth:api', ['except' => ['login']]);
    }

    /**
     * Get a JWT via given credentials.
     *
     * @return \Illuminate\Http\JsonResponse
     */
    public function login()
    {
        $credentials = request(['email', 'password']);

        if (! $token = auth()->attempt($credentials)) {
            return response()->json(['error' => 'Unauthorized'], 401);
        }

        return $this->respondWithToken($token);
    }

    /**
     * Get the authenticated User.
     *
     * @return \Illuminate\Http\JsonResponse
     */
    public function me()
    {
        return response()->json(auth()->user());
    }

    /**
     * Log the user out (Invalidate the token).
     *
     * @return \Illuminate\Http\JsonResponse
     */
    public function logout()
    {
        auth()->logout();

        return response()->json(['message' => 'Successfully logged out']);
    }

    /**
     * Refresh a token.
     *
     * @return \Illuminate\Http\JsonResponse
     */
    public function refresh()
    {
        return $this->respondWithToken(auth()->refresh());
    }

    /**
     * Get the token array structure.
     *
     * @param  string $token
     *
     * @return \Illuminate\Http\JsonResponse
     */
    protected function respondWithToken($token)
    {
        return response()->json([
            'access_token' => $token,
            'token_type' => 'bearer',
            'expires_in' => auth()->factory()->getTTL() * 60
        ]);
    }
}
```

--------------------------------

### login()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Log a user in and return a JWT for them.

```APIDOC
## login()

### Description
Log a user in and return a JWT for them.

### Method
login

### Parameters
- **$user** (object) - Required - The user object to log in.

### Request Example
```php
$user = User::first();
$token = auth()->login($user);
```

### Response
- **string** - The JWT token.

### Response Example
```php
$token = 'eyJhb...';
```
```

--------------------------------

### Attempt authentication with auth()->attempt()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Attempt to authenticate a user with credentials. Returns a JWT on success or null on failure.

```php
// Generate a token for the user if the credentials are valid
$token = auth()->attempt($credentials);
```

--------------------------------

### Generate certificates

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/generate-secrets.md

Generates certificates and updates the .env file to use them. Accepts parameters like force, algo, bits, curve, sha, passphrase, ask-passphrase, and dir.

```bash
php artisan jwt:generate-certs
```

--------------------------------

### Add custom claims with auth()->claims()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Add custom claims to the token by chaining claims() before attempt().

```php
$token = auth()->claims(['foo' => 'bar'])->attempt($credentials);
```

--------------------------------

### Publish jwt-auth Config

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/laravel-installation.md

Publishes the package config file, creating config/jwt.php for configuring the package basics.

```bash
php artisan vendor:publish --provider="PHPOpenSourceSaver\JWTAuth\Providers\LaravelServiceProvider"
```

--------------------------------

### Enable auth middleware in Lumen

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/lumen-installation.md

Uncomment the auth middleware in bootstrap/app.php to enable authentication.

```php
$app->routeMiddleware([
    'auth' => App\Http\Middleware\Authenticate::class,
]);
```

--------------------------------

### Add basic authentication routes

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/quick-start.md

Add authentication routes in routes/api.php. Defines login, logout, refresh, and me endpoints under the auth prefix with the api middleware.

```php
Route::group([

    'middleware' => 'api',
    'prefix' => 'auth'

], function ($router) {

    Route::post('login', 'AuthController@login');
    Route::post('logout', 'AuthController@logout');
    Route::post('refresh', 'AuthController@refresh');
    Route::post('me', 'AuthController@me');

});
```

--------------------------------

### attempt()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Attempt to authenticate a user via some credentials. Returns a JWT token if credentials are valid, otherwise null.

```APIDOC
## attempt()

### Description
Attempt to authenticate a user via some credentials. Returns a JWT token if credentials are valid, otherwise null.

### Method
attempt

### Parameters
- **$credentials** (array) - Required - The user credentials.

### Request Example
```php
$token = auth()->attempt($credentials);
```

### Response
- **string|null** - The JWT token if successful, otherwise null.

### Response Example
```php
$token = 'eyJhb...';
```
```

--------------------------------

### Authenticate with a specific guard using auth('api')->attempt()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Specify the guard name when the 'api' guard is not the default or multiple guards are defined.

```php
$token = auth('api')->attempt($credentials);
```

--------------------------------

### Generate RSA certificate with 4096 bits and SHA-512

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/generate-secrets.md

Generates a 4096-bit RSA certificate with SHA-512 hashing. The --force flag overrides existing certificates.

```bash
php artisan jwt:generate-certs --force --algo=rsa --bits=4096 --sha=512
```

--------------------------------

### Register Auth and Lumen Service Providers

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/lumen-installation.md

Register the AuthServiceProvider and the LumenServiceProvider in the providers section of bootstrap/app.php.

```php
// Uncomment this line
$app->register(App\Providers\AuthServiceProvider::class);

// Add this line
$app->register(PHPOpenSourceSaver\JWTAuth\Providers\LumenServiceProvider::class);
```

--------------------------------

### Configure guards with custom TTLs in config/auth.php

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/configuration.md

Shows how to set custom TTLs for JWT guards. The 'customers' guard uses a 15-minute TTL, 'administrators' has no expiration (null), and 'users' falls back to the global TTL.

```php
'guards' => [
    'customers' => [
        'driver' => 'jwt',
        'provider' => 'customers',
        'ttl' => env('JWT_CUSTOMERS_TTL', 15), // Custom TTL for 'customers' guard (15 minutes)
    ],
    'administrators' => [
        'driver' => 'jwt',
        'provider' => 'administrators',
        'ttl' => null, // 'administrators' guard has no expiration
    ],
    // if no 'ttl' is set, it will use the 'ttl' value in `config/jwt.php`
    'users' => [
        'driver' => 'jwt',
        'provider' => 'users',
    ],
],
```

--------------------------------

### Generate EC certificate with prime256v1 curve and SHA-512

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/generate-secrets.md

Generates an EC certificate using the prime256v1 curve and SHA-512 hashing. The --force flag overrides existing certificates.

```bash
php artisan jwt:generate-certs --force --algo=ec --curve=prime256v1 --sha=512
```

--------------------------------

### claims()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Add custom claims to the token.

```APIDOC
## claims()

### Description
Add custom claims to the token.

### Method
claims

### Parameters
- **$claims** (array) - Required - The custom claims to add.

### Request Example
```php
$token = auth()->claims(['foo' => 'bar'])->attempt($credentials);
```
```

--------------------------------

### Refresh token with auth()->refresh()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Refresh a token, invalidating the current one. The first parameter forces blacklisting forever; the second resets claims for the new token.

```php
$newToken = auth()->refresh();

// Pass true as the first param to force the token to be blacklisted "forever".
// The second parameter will reset the claims for the new token
$newToken = auth()->refresh(true, true);
```

--------------------------------

### Configure jwt in Lumen bootstrap

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/lumen-installation.md

Register the jwt configuration file in the Lumen application. Add this to bootstrap/app.php before middleware declaration.

```php
$app->configure('jwt');
```

--------------------------------

### setToken()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Set the token explicitly.

```APIDOC
## setToken()

### Description
Set the token explicitly.

### Method
setToken

### Parameters
- **$token** (string) - Required - The JWT token.

### Request Example
```php
$user = auth()->setToken('eyJhb...')->user();
```
```

--------------------------------

### Log out and invalidate token with auth()->logout()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Log out the user, invalidating the current token and unsetting the authenticated user. Passing true forces the token to be blacklisted forever.

```php
auth()->logout();

// Pass true to force the token to be blacklisted "forever"
auth()->logout(true);
```

--------------------------------

### setRequest()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Set the request instance explicitly.

```APIDOC
## setRequest()

### Description
Set the request instance explicitly.

### Method
setRequest

### Parameters
- **$request** (object) - Required - The request instance.

### Request Example
```php
$user = auth()->setRequest($request)->user();
```
```

--------------------------------

### setTTL()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Override the token TTL.

```APIDOC
## setTTL()

### Description
Override the token TTL.

### Method
setTTL

### Parameters
- **$ttl** (int) - Required - The TTL in minutes.

### Request Example
```php
$token = auth()->setTTL(120)->attempt($credentials);
```
```

--------------------------------

### Validate credentials with auth()->validate()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Validate a user's credentials without logging them in.

```php
if (auth()->validate($credentials)) {
    // credentials are valid
}
```

--------------------------------

### validate()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Validate a user's credentials.

```APIDOC
## validate()

### Description
Validate a user's credentials.

### Method
validate

### Parameters
- **$credentials** (array) - Required - The user credentials.

### Request Example
```php
if (auth()->validate($credentials)) {
    // credentials are valid
}
```

### Response
- **bool** - True if credentials are valid, false otherwise.
```

--------------------------------

### Add Service Provider to config/app.php

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/laravel-installation.md

Adds the LaravelServiceProvider to the providers array in config/app.php for Laravel 5.4 or below.

```php
'providers' => [

    ...

    PHPOpenSourceSaver\JWTAuth\Providers\LaravelServiceProvider::class,
]
```

--------------------------------

### Configure Auth guard with jwt driver

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/quick-start.md

Configure the api guard to use the jwt driver in config/auth.php. Only works with Laravel 5.2 and above. Sets the api guard as the default.

```php
'defaults' => [
    'guard' => 'api',
    'passwords' => 'users',
],

...

'guards' => [
    'api' => [
        'driver' => 'jwt',
        'provider' => 'users',
    ],
],
```

--------------------------------

### logout()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Log the user out, invalidating the current token and unsetting the authenticated user.

```APIDOC
## logout()

### Description
Log the user out, invalidating the current token and unsetting the authenticated user.

### Method
logout

### Parameters
- **$force** (bool) - Optional - Pass true to force the token to be blacklisted "forever".

### Request Example
```php
auth()->logout();
// Pass true to force the token to be blacklisted "forever"
auth()->logout(true);
```
```

--------------------------------

### Send token via query string parameter

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/quick-start.md

Send the JWT token as a query string parameter named 'token'. This method is less secure than headers and should be used with caution.

```http
http://example.dev/me?token=eyJhbGciOiJIUzI1NiI...
```

--------------------------------

### refresh()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Refresh a token, which invalidates the current one.

```APIDOC
## refresh()

### Description
Refresh a token, which invalidates the current one.

### Method
refresh

### Parameters
- **$force** (bool) - Optional - Pass true to force the token to be blacklisted "forever".
- **$resetClaims** (bool) - Optional - Pass true to reset the claims for the new token.

### Request Example
```php
$newToken = auth()->refresh();
// Pass true as the first param to force the token to be blacklisted "forever".
// The second parameter will reset the claims for the new token
$newToken = auth()->refresh(true, true);
```

### Response
- **string** - The new JWT token.

### Response Example
```php
$newToken = 'eyJhb...';
```
```

--------------------------------

### Update User model with JWTSubject contract

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/quick-start.md

Implement the JWTSubject contract on your User model. Requires the getJWTIdentifier() and getJWTCustomClaims() methods. Adjust as needed for your own needs.

```php
<?php

namespace App;

use PHPOpenSourceSaver\JWTAuth\Contracts\JWTSubject;
use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable implements JWTSubject
{
    use Notifiable;

    // Rest omitted for brevity

    /**
     * Get the identifier that will be stored in the subject claim of the JWT.
     *
     * @return mixed
     */
    public function getJWTIdentifier()
    {
        return $this->getKey();
    }

    /**
     * Return a key value array, containing any custom claims to be added to the JWT.
     *
     * @return array
     */
    public function getJWTCustomClaims()
    {
        return [];
    }
}
```

--------------------------------

### Generate JWT secret key

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/generate-secrets.md

Generates a secret key and updates the .env file with a JWT_SECRET value. The key is used to sign tokens, with the signing method depending on the chosen algorithm.

```bash
php artisan jwt:secret
```

--------------------------------

### Invalidate token with auth()->invalidate()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Invalidate the token by adding it to the blacklist. Passing true forces the token to be blacklisted forever.

```php
auth()->invalidate();

// Pass true as the first param to force the token to be blacklisted "forever".
auth()->invalidate(true);
```

--------------------------------

### Send token via Authorization header

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/quick-start.md

Send the JWT token in the Authorization header using the Bearer scheme. This is a common way to authenticate requests.

```http
Authorization: Bearer eyJhbGciOiJIUzI1NiI...
```

--------------------------------

### Set JWT secret in config/jwt.php

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/configuration.md

Defines the JWT secret using the JWT_SECRET environment variable. This is the default option in the published config file.

```php
'secret' => env('JWT_SECRET'),
```

--------------------------------

### invalidate()

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/auth-guard.md

Invalidate the token (add it to the blacklist).

```APIDOC
## invalidate()

### Description
Invalidate the token (add it to the blacklist).

### Method
invalidate

### Parameters
- **$force** (bool) - Optional - Pass true to force the token to be blacklisted "forever".

### Request Example
```php
auth()->invalidate();
// Pass true as the first param to force the token to be blacklisted "forever".
auth()->invalidate(true);
```
```

--------------------------------

### Customize JWT cookie name in config/jwt.php

Source: https://github.com/php-open-source-saver/jwt-auth/blob/main/docs/quick-start.md

Configure the cookie name used for JWT authentication. The default key name is 'token'. When making requests, the token is automatically read from the specified cookie.

```php
// config/jwt.php

return [
    // ...
    'cookie_name' => 'token',
    // ...
];
```
Tokens:
Raw