= Documentation for JWT Refresh Feature

The jwt_refresh feature adds support for a database-backed JWT refresh token,
setting a short lifetime on JWT access tokens.

When this feature is used, the access and refresh token are provided
at login in the response body (the access token is still provided in the Authorization
header), and for any subsequent POST to <tt>/jwt-refresh</tt>.

Note that using the refresh token invalidates the token and creates
a new access token with an updated lifetime.  However, it does not invalidate
older access tokens.  Older access tokens remain valid until they expire.  You
can use the active_sessions feature if you want previous access tokens to be invalid
as soon as the refresh token is used.

You can have multiple active refresh tokens active at a time, since each browser session
will generally use a separate refresh token.  If you would like to revoke a refresh token
when logging out, provide the refresh token when submitting the JSON request to logout.
If you would like to remove all refresh tokens for the account when logging out, provide
a value of <tt>all</tt> as the token value.

When using the refresh token, you must provide a valid access token, as that contains
information about the current session, which is used to create the new access token.
If you change the +allow_refresh_with_expired_jwt_access_token?+ setting to +true+,
an expired but otherwise valid access token will be accepted, and Rodauth will check
that the access token was issued in the same session as the refresh token.

When an account change is made made during a logged in session (such as a login change),
refresh tokens are not automatically invalidated, as Rodauth does not know which refresh
token is being used for the current session. It is recommended that you use the
active_sessions feature if you would like an account change during a logged in session
to invalidate refresh tokens. Technically, this invalides the account tokens for other
sessions and not the refresh tokens, but you need a valid access token to use the
refresh token, so it has the same effect.

This feature depends on the jwt feature.

== Auth Value Methods

allow_refresh_with_expired_jwt_access_token? :: Whether refreshing should be allowed with an expired access token. Default is +false+.  You must set an +hmac_secret+ if setting this value to +true+.
expired_jwt_access_token_status :: The HTTP status code to use when a access token (JWT) is expired is submitted in the Authorization header. Default is 400 for backwards compatibility, and it is recommended to set it to 401.
expired_jwt_access_token_message :: The error message to use when a access token (JWT) is expired is submitted in the Authorization header.
jwt_access_token_key :: Name of the key in the response json holding the access token.  Default is +access_token+.
jwt_access_token_not_before_period :: How many seconds before the current time will the jwt be considered valid (to account for inaccurate clocks). Default is 5.
jwt_access_token_period :: Validity of an access token in seconds, default is 1800 (30 minutes).
jwt_refresh_route :: The route to the login action. Defaults to <tt>jwt-refresh</tt>.
jwt_refresh_invalid_token_message :: Error message when the provided refresh token is non existent, invalid or expired.
jwt_refresh_token_account_id_column :: The column name in the +jwt_refresh_token_table+ storing the account id, should be a foreign key referencing the accounts table.
jwt_refresh_token_data_session_key :: The key in the session hash storing random data, for access checking during refresh if +allow_refresh_with_expired_jwt_access_token?+ is set.
jwt_refresh_token_deadline_column :: The column name in the +jwt_refresh_token_table+ storing the deadline after which the refresh token will no longer be valid.
jwt_refresh_token_deadline_interval :: Validity of a refresh token. Default is 14 days.
jwt_refresh_token_hmac_session_key :: The key in the session hash storing the hmac, for access checking during refresh if +allow_refresh_with_expired_jwt_access_token?+ is set.
jwt_refresh_token_id_column :: The column name in the refresh token keys table storing the id of each token (the primary key of the table).
jwt_refresh_token_key :: Name of the key in the response json holding the refresh token.  Default is +refresh_token+.
jwt_refresh_token_key_column :: The column name in the +jwt_refresh_token_table+ holding the refresh token key value.
jwt_refresh_token_key_param :: Name of parameter in which the refresh token is provided when requesting a new token.  Default is +refresh_token+.
jwt_refresh_token_table :: Name of the table holding refresh token keys.
jwt_refresh_without_access_token_message :: Error message when trying to refresh with providing an access token.
jwt_refresh_without_access_token_status :: The HTTP status code to use when trying to refresh without providing an access token.

== Auth Methods

account_from_refresh_token(token) :: Returns the account hash for the given refresh token.
after_refresh_token :: Hooks for specific processing once the refresh token has been set.
before_jwt_refresh_route :: Run arbitrary code before handling a jwt_refresh route.
before_refresh_token :: Hooks for specific processing before the refresh token is computed.
