Clarification on Refresh Token Behaviour

[Bruno Bernard]

Clarify JWT Token Behaviour

Explanation

The tymondesigns/jwt-auth access token has an hybrid behaviour. It can be used as a refresh token and as an access token. Once it has passed the expiration time in minutes, It will be invalid as an access token but it will still be valid as a refresh token. When the token is refreshed, the token sent is invalidated (means you cannot use it anymore) and a new token is returned. So once you call ->refresh() it will invalidate the JWT token previously generated.

Exclude refresh in middleware

Endpoint which has a refresh behavoir should not be using the middleware 'auth:api'. Example:

$this->middleware('auth:api')->except(['refresh']);

or do not include it in a group route middleware.

Behavior: Only call refresh() when you need to refresh.

if you want a behaviour where the JSON has a refresh and a access_token, generate a token, then use same for both.

$token = auth()->attempt($credentials); // or ->login($user);
//...
// DO NOT CALL `->refresh()` else it will invalidate the access token.
return [
   "access_token" => $token, 
   "refresh_token" => $token
];

Configuration is for the SAME token

The ttl and refresh_ttl in the jwt.php config is for the same token.

Thanks to:
#2219

Fixes:
#2116
#2209
#2205
#2201
#2149
#2136
#2116
and maybe more ....

@tymondesigns to close all those issues and add this to the docs.