Last Update: 2017-10-27 14:49:32 -0700

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 authentication data.

When this feature is used, all other features become accessible via a JSON API. The JSON API uses the POST method for all requests, using the same parameter names as the features uses. JSON API requests to Rodauth endpoints that use a method other than POST will result in a 405 Method Not Allowed response.

Responses are returned as JSON hashes. In case of an error, the “error” entry is set to an error message, and the “field-error” entry is set to an array containing the field name and the error message for that field. Successful requests by default store a “success” entry with a success message, though that can be disabled.

In order to use this feature, you have to set the jwt_secret configuration option 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.

Auth Value Methods


The error message to use when a JWT with an invalid format is submitted in the Authorization header.


The regexp to use to check the Accept header for JSON if jwt_check_accept? is true.


The error message to use when a JSON non-POST request is sent.


The error message to display if jwt_check_accept? is true and the Accept header is present but does not match json_request_content_type_regexp.


The regexp to use to recognize a request as a json request.


The content type to set for json responses, application/json by default.


Whether to use custom error statuses, instead of always using json_response_error_status, false by default for backwards compatibility.


The JSON result key containing an error message, “error” by default.


The HTTP status code to use for JSON error responses, 400 by default.


The JSON result key containing an field error message, “field-error” by default.


The JSON result key containing a success message for successful request, if set. nil by default to not set success messages.


The JWT algorithm to use, “HS256” by default.


A regexp matched against the Authorization header, which skips JWT processing if it matches. By default, HTTP Basic and Digest authentication are ignored.


A regexp to remove from the Authorization header before processing the JWT. By default, a Bearer prefix is removed.


Whether to check the Accept header to see if the client supports JSON responses, false by default for backwards compatibility.


An optional hash to pass to JWT.decode. Can be used to set JWT verifiers.


The JWT secret to use. Access to this should be protected the same as a session secret.


A key to nest the session hash under in the JWT payload. nil by default, for no nesting.


Whether to symbolize the session hash deeply. false by default.


The error message to use when a non-JSON request is sent and only_json? is set.


Whether to have Rodauth only allow JSON requests. True by default if :json=>:only option was given when loading the plugin. If set, rodauth endpoints will issue an error for non-JSON requests.


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


Whether the current request is a JSON request, looks at the Content-Type request header by default.


The body to use for JSON response. By default just converts hash to JSON. Can be used to reformat JSON output in arbitrary ways.


The session hash used to create the session_jwt. Can be used to set JWT claims.


Retrieve the JWT token from the request, by default taking it from the Authorization header.


An encoded JWT for the current session.


Set the JWT token in the response, by default storing it in the Authorization header.