Last Update: 2023-05-26 08:58:22 -0700

Documentation for JSON Feature

The json feature adds support for JSON API access for all other features that ship with Rodauth.

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.

The JSON response can be modified at any point by modifying the json_response hash. The following example adds an error reason to the JSON response:

set_error_reason do |reason|
  json_response[:error_reason] = reason

The session state is managed in the rack session, so make sure that CSRF protection is enabled. This will be the case when passing the json: true option when loading the rodauth plugin. If you want to only handle JSON requests, set only_json? true in your rodauth configuration.

If you want token-based authentication sent via the Authorization header, consider using the jwt feature.

Auth Value Methods


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


Whether to check the Accept header to see if the client supports JSON responses, true by default.


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


The error message to display if json_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, true by default, can be set to false for backwards compatibility with Rodauth 1.


Whether the current JSON response indicates an error. By default, returns whether json_response_error_key is set.


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


The HTTP status code to use for JSON error responses if not using custom error statuses, 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. success 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 return a JSON response. By default, a JSON response is returned 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.