Documentation for JWT Feature¶ ↑

The jwt feature adds support for JSON API access for all other features that ship with Rodauth, using JWT (JSON Web Tokens) to hold the session information. It depends on the json feature.

In order to use this feature, you have to set the jwt_secret configuration option with the secret used to cryptographically protect the token.

To use this JSON API, when processing responses for requests to a Rodauth endpoint, check for the Authorization header, and use the value of the response Authorization header as the request Authorization header in future requests, if the response Authorization header is set. If the response Authorization header is not set, then continue to use the previous Authorization header.

When using this feature, consider using the json: :only option when loading the rodauth plugin, if you want Rodauth to only handle JSON requests. If you don’t use the json: :only option, the jwt feature will probably result in an error if a request to a Rodauth endpoint comes in with a Content-Type that isn’t application/json, unless you also set only_json? false in your rodauth configuration.

If you would like to check if a valid JWT was submitted with the current request in your Roda app, you can call the rodauth.valid_jwt? method. If rodauth.valid_jwt? returns true, the contents of the jwt can be retrieved from rodauth.session.

Logging the session out does not invalidate the previous JWT token by default. If you would like this behavior, you can use the active_sessions feature, which stores session identifiers in the database and deletes them when the session expires. This provides a whitelist approach of revoking JWT tokens.

Auth Value Methods¶ ↑

invalid_jwt_format_error_message	The error message to use when a JWT with an invalid format is submitted in the Authorization header.
jwt_algorithm	The JWT algorithm to use, HS256 by default.
jwt_authorization_ignore	A regexp matched against the Authorization header, which skips JWT processing if it matches. By default, HTTP Basic and Digest authentication are ignored.
jwt_authorization_remove	A regexp to remove from the Authorization header before processing the JWT. By default, a Bearer prefix is removed.
jwt_decode_opts	An optional hash to pass to JWT.decode. Can be used to set JWT verifiers.
jwt_old_secret	The previous JWT secret used, to support JWT secret rotation (only supported when using jwt 2.4+). Access to this should be protected the same as a session secret.
jwt_secret	The JWT secret to use. Access to this should be protected the same as a session secret.
jwt_session_key	A key to nest the session hash under in the JWT payload. nil by default, for no nesting.
jwt_symbolize_deeply?	Whether to symbolize the session hash deeply. false by default.
use_jwt?	Whether to use the JWT in the Authorization header for authentication information. If false, falls back to using the rack session. By default, the Authorization header is used if it is present, if only_json? is true, or if the request uses a json content type.

Auth Methods¶ ↑

jwt_session_hash	The session hash used to create the session_jwt. Can be used to set JWT claims.
jwt_token	Retrieve the JWT token from the request, by default taking it from the Authorization header.
session_jwt	An encoded JWT for the current session.
set_jwt_token(token)	Set the JWT token in the response, by default storing it in the Authorization header.