AuthKit

Easy to use authentication platform designed to provide a flexible, secure, and fast integration.

Quickly integrate AuthKit in your project with the AI-powered WorkOS CLI.

 npx workos@latest

What you’ll build

In this guide, you’ll add a complete hosted authentication flow to your application using AuthKit. By the end, you’ll have signup, sign-in, and session management working end-to-end.

For additional implementation patterns, see the example apps.

Before getting started

Make sure you have:

A WorkOS account
Your WorkOS API Key and Client ID

Activate AuthKit in your WorkOS Dashboard if you haven’t already. In the Overview section, click the Set up AuthKit button and follow the instructions.

WorkOS dashboard with the AuthKit setup button highlighted

1. Configure your project

Add the necessary dependencies and configure your WorkOS Dashboard.

Install dependencies

First, install the WorkOS gem.

Install Ruby SDK

 gem install workos

Configure a redirect URI

A redirect URI is a callback endpoint that WorkOS redirects to after a user has authenticated. This endpoint exchanges the authorization code returned by WorkOS for an authenticated User object.

Set a redirect URI in the Redirects section of the WorkOS Dashboard. Use http://localhost:3000/callback as the default.

WorkOS supports using wildcard characters in Redirect URIs, but not for the default Redirect URI. More information about wildcard characters support can be found in the Redirect URIs guide.

When users sign out of their application, they will be redirected to your app’s Sign-out redirect location which is configured in the same dashboard area.

Sign-in requests should originate from your application. In some instances, requests may not begin at your app. For example, some users might bookmark the hosted sign-in page or they might be led directly to the hosted sign-in page when clicking on a password reset link in an email.

In these cases, AuthKit detects when a sign-in request did not originate at your application and redirects to your application’s sign-in endpoint. This is an endpoint that you define at your application that redirects users to sign in using AuthKit.

Configure the sign-in endpoint from the Redirects section of the WorkOS dashboard.

Set secrets

To make calls to WorkOS, provide the API key and the client ID. Store these values as managed secrets and pass them to the SDKs either as environment variables or directly in your app’s configuration depending on your preferences.

Environment variables

 WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'

The code examples use your staging API keys when signed in

2. Add AuthKit to your app

Integrate the hosted authentication flow into your app.

Set up the frontend

To demonstrate AuthKit, we only need a simple page with links to logging in and out.

JavaScript

 export default function App() {
  return (
    <div className="App">
      <h1>AuthKit example</h1>
      <p>This is an example of how to use AuthKit with a React frontend.</p>
      <p>
        <a href="/login">Sign in</a>
      </p>
      <p>
        <a href="/logout">Sign out</a>
      </p>
    </div>
  );
}

Clicking the “Sign in” and “Sign out” links should invoke actions on our server, which we’ll set up next.

Create a sign-in endpoint to direct users to sign in (or sign up) using AuthKit before redirecting them back to your application. This endpoint generates an AuthKit authorization URL server side and redirects the user to it.

Use the optional state parameter to encode arbitrary information to help restore application state between redirects.

This guide uses the sinatra web server for Ruby. For more information on setting up Sinatra, see the Sinatra documentation.

server.rb

Ruby

 require "dotenv/load"
require "workos"
require "sinatra"

WorkOS.configure do |config|
  config.key = ENV["WORKOS_API_KEY"]
end

set :port, 3000

get "/" do
  send_file "index.html"
end

get "/login" do
  authorization_url = WorkOS::UserManagement.authorization_url(
    provider: "authkit",
    client_id: ENV["WORKOS_CLIENT_ID"],
    redirect_uri: "http://localhost:3000/callback"
  )

  redirect authorization_url
end

WorkOS will redirect to your Redirect URI if there is an issue generating an authorization URL. Read our API Reference for more details.

Add a callback endpoint

Next, add the callback endpoint (referenced in Configure a redirect URI) to exchange the authorization code (valid for 10 minutes) for an authenticated User object.

server.rb

Ruby

 get "/callback" do
  code = params["code"]

  begin
    auth_response = WorkOS::UserManagement.authenticate_with_code(
      client_id: ENV["WORKOS_CLIENT_ID"],
      code: code
    )

    # Use the information in auth_response for further business logic.

    redirect "/"
  rescue => e
    puts e
    redirect "/login"
  end
end

3. Handle the user session

Session management helper methods are included in our SDKs to make integration easy. For security reasons, sessions are automatically “sealed”, meaning they are encrypted with a strong password.

Create a session password

The SDK requires you to set a strong password to encrypt cookies. This password must be 32 characters long. You can generate a secure password by using the 1Password generator or the openssl library via the command line:

Generate a strong password

 openssl rand -base64 32

Add it to the environment variables file.

.env

 WORKOS_API_KEY='sk_example_123456789'
WORKOS_CLIENT_ID='client_123456789'

WORKOS_COOKIE_PASSWORD='<your password>'

Save the encrypted session

Use the SDK to authenticate the user and return a password-protected session. The refresh token is considered sensitive as it can be used to re-authenticate, so encrypt the session before storing it in a session cookie.

server.rb

Ruby

 get "/callback" do
  code = params["code"]

  begin
    auth_response = WorkOS::UserManagement.authenticate_with_code(
      client_id: ENV["WORKOS_CLIENT_ID"],
      code: code,
      session: {
        seal_session: true,
        cookie_password: ENV["WORKOS_COOKIE_PASSWORD"]
      }
    )

    # store the session in a cookie
    response.set_cookie(
      "wos_session",
      value: auth_response.sealed_session,
      httponly: true,
      secure: true,
      samesite: "lax"
    )

    # Use the information in auth_response for further business logic.

    redirect "/"
  rescue => e
    puts e
    redirect "/login"
  end
end

Present user information on the frontend. Update the default route to read the session cookie and display user information:

server.rb

Ruby

 get "/" do
  session_cookie = request.cookies["wos_session"]
  user = nil

  if session_cookie
    begin
      session = WorkOS::UserManagement.load_sealed_session(
        client_id: ENV["WORKOS_CLIENT_ID"],
        session_data: session_cookie,
        cookie_password: ENV["WORKOS_COOKIE_PASSWORD"]
      )

      auth_result = session.authenticate
      user = auth_result[:user]
    rescue => e
      puts "Error loading session: #{e.message}"
    end
  end

  user_info = user ? %(<p>Welcome, #{user[:email]}!</p>) : ""

  html = File.read("index.html")
  html.gsub("{{USER_DATA}}", user_info)
end

Update the index page to present this info.

index.html

HTML

 <!doctype html>
<html lang="en">
  <head>
    <title>AuthKit example</title>
  </head>
  <body>
    <h1>AuthKit example</h1>
    {{USER_DATA}}
    <p>This is an example of how to use AuthKit with an HTML frontend.</p>
    <p>
      <a href="/login">Sign in</a>
    </p>
    <p>
      <a href="/logout">Sign out</a>
    </p>
  </body>
</html>

Protected routes

Use a helper method to specify which routes should be protected. If the session has expired, use the SDK to attempt to generate a new one.

server.rb

Ruby

 helpers do
  def with_auth(request, response)
    session = WorkOS::UserManagement.load_sealed_session(
      client_id: ENV["WORKOS_CLIENT_ID"],
      session_data: request.cookies["wos_session"],
      cookie_password: ENV["WORKOS_COOKIE_PASSWORD"]
    )

    session.authenticate => { authenticated:, reason: }

    return if authenticated == true

    redirect "/login" if !authenticated && reason == "NO_SESSION_COOKIE_PROVIDED"

    # If no session, attempt a refresh
    begin
      session.refresh => { authenticated:, sealed_session: }

      redirect "/login" if !authenticated

      response.set_cookie(
        "wos_session",
        value: sealed_session,
        httponly: true,
        secure: true,
        samesite: "lax"
      )

      # Redirect to the same route to ensure the updated cookie is used
      redirect request.url
    rescue => e
      warn e
      response.delete_cookie("wos_session")
      redirect "/login"
    end
  end
end

Call the helper method in the route that should only be accessible to logged-in users.

server.rb

Ruby

 get "/dashboard" do
  with_auth(request, response)

  session = WorkOS::UserManagement.load_sealed_session(
    client_id: ENV["WORKOS_CLIENT_ID"],
    session_data: request.cookies["wos_session"],
    cookie_password: ENV["WORKOS_COOKIE_PASSWORD"]
  )

  session.authenticate => { authenticated:, user: }

  redirect "/login" if !authenticated

  puts "User #{user[:first_name]} is logged in"

  # Render a dashboard view
end

Ending the session

Finally, ensure the user can end their session by redirecting them to the logout URL. After successfully signing out, the user will be redirected to your app’s Sign-out redirect location, which is configured in the WorkOS dashboard.

server.rb

Ruby

 get "/logout" do
  session = WorkOS::UserManagement.load_sealed_session(
    client_id: ENV["WORKOS_CLIENT_ID"],
    session_data: request.cookies["wos_session"],
    cookie_password: ENV["WORKOS_COOKIE_PASSWORD"]
  )

  url = session.get_logout_url

  response.delete_cookie("wos_session")

  # After log out has succeeded, the user will be redirected to your
  # app homepage which is configured in the WorkOS dashboard
  redirect url
end

If you haven’t configured a Sign-out redirect in the WorkOS dashboard, users will see an error when logging out.

Validate the authentication flow

Start your server with ruby server.rb, navigate to localhost:3000, and sign up for an account.

Example appsView sample AuthKit apps

Up next

AuthKit

What you’ll build

Before getting started

1. Configure your project

Install dependencies

Configure a redirect URI

Configure sign-in endpoint

Set secrets

2. Add AuthKit to your app

Set up the frontend

Add a sign-in endpoint

Add a callback endpoint

3. Handle the user session

Create a session password

Save the encrypted session

Protected routes

Ending the session

Validate the authentication flow