JSON API

JSON (cookie-based)

To make Rodauth endpoints accessible via JSON API, enable the json feature:

# app/misc/rodauth_main.rb
class RodauthMain < Rodauth::Rails::Auth
  configure do
    # ...
    enable :json
    only_json? true # accept only JSON requests (optional)
    # ...
  end
end

This will store account session data into the Rails session. If you're using Rails in API-only mode, make sure to enable session store in Rails configuration:

# config/application.rb
module MyApp
  class Application < Rails::Application
    # ...
    config.session_store :cookie_store, key: '_your_app_api_session'
    config.middleware.use ActionDispatch::Cookies
    config.middleware.use config.session_store, config.session_options
    # ...
  end
end

JWT (token-based)

If you rather want stateless token-based authentication via the Authorization header, enable the jwt feature (which builds on top of the json feature) and add the JWT gem to the Gemfile:

$ bundle add jwt

# app/misc/rodauth_main.rb
class RodauthMain < Rodauth::Rails::Auth
  configure do
    # ...
    enable :jwt
    jwt_secret "<YOUR_SECRET_KEY>" # store the JWT secret in a safe place
    only_json? true # accept only JSON requests (optional)
    # ...
  end
end

The JWT token will be returned after each request to Rodauth routes. To also return the JWT token on requests to your app's routes, you can add the following code to your base controller:

class ApplicationController < ActionController::Base
  # ...
  after_action :set_jwt_token

  private

  def set_jwt_token
    if rodauth.use_jwt? && rodauth.valid_jwt?
      response.headers["Authorization"] = rodauth.session_jwt
    end
  end
  # ...
end

Email links

When using JSON API mode with only_json? set to true, only POST endpoints are available (GET endpoints are disabled). This means that following email links (account verification, password reset, login change etc.) will not automatically work if the URL points to the backend API.

The emails links need to point to a frontend app, which should then make a POST request to the backend using the token from the URL, hitting the Rodauth endpoint. URL options for background emails can be modified through config.action_mailer.default_url_options, and those should point to the frontend app.

config.action_mailer.default_url_options = { scheme: "https", host: "frontend.example.com" }

If you don't want the frontend routes to use the same URL path as the backend Rodauth endpoints, you can override the *_email_link methods with the frontend URL, passing it the token:

class RodauthMain < Rodauth::Rails::Auth
  configure do
    verify_account_email_link do
      "https://frontend.example.com/account/verify?token=#{token_param_value(verify_account_key_value)}"
    end
  end
end

API documentation

If you'd like to get an overview of the routes available to you and the parameters they accept, you can use the rodauth-openapi gem to generate OpenAPI documentation from your Rodauth configuration.

$ bundle add rodauth-openapi --group development
$ rails g rodauth:openapi --save api-docs.yml

You can then upload the result into an OpenAPI renderer such as Swagger Editor or Redocly, and see the available routes.