A Complete Guide to Integrating WorkOS AuthKit with Ruby on Rails

Authentication is one of those fundamentals in modern web development that's deceptively easy to get wrong. WorkOS AuthKit offers a ready-to-use authentication solution, but putting it into production inside a Ruby on Rails application still requires careful attention to detail. This article focuses on the session layer beneath the CLI login flow — what's actually stored inside a sealed cookie, how to refresh sessions in a before_action, and three WorkOS console settings that most commonly cause logout to silently break in production.

The Core of the Session Layer: What's Inside a Sealed Cookie

The WorkOS AuthKit CLI can walk you through the login flow quickly, but what actually sustains user state after a successful login is the session layer. The key carrier of that layer is the sealed cookie.

A sealed cookie is an encrypted, encapsulated session credential. Rather than simply writing a plain-text user ID into the browser, it packages authentication state, token information, and related data into an encrypted payload stored on the client side. The upside is that the server doesn't need to maintain any additional storage per session, while the credential contents remain tamper-proof and unreadable. Understanding the data structure carried inside a sealed cookie is foundational for debugging authentication issues down the line — when sessions unexpectedly expire or users are repeatedly prompted to log in again, the problem almost always traces back to this layer.

Refreshing Sessions in a before_action

Rails' before_action is a natural entry point for handling authentication logic. Placing session refresh logic here ensures that every protected request checks — and if necessary refreshes — the user's authentication state before the controller action actually executes.

The value of session refresh is extending a user's valid login window and preventing them from being forcibly logged out when a token expires. The typical approach is to inspect the token inside the current sealed cookie inside the before_action callback, and if the token is approaching expiry, call WorkOS's refresh endpoint to obtain a new token, then re-seal and write it back into the cookie. This entire process is completely transparent to the user, and it's the key to delivering a smooth login experience.

One thing to keep in mind: the refresh logic needs to balance performance and security. Refreshing on every single request causes unnecessary API calls, but refreshing too conservatively leads to sessions expiring too early. A sensible strategy is to set a refresh threshold — only trigger a refresh when the token's remaining validity falls below that threshold.

Three Console Configuration Traps That Break Logout in Production

Everything works fine in development, but logout stops working the moment you deploy to production — this is one of the most common problems developers encounter when integrating WorkOS AuthKit. The root cause almost always traces back to three settings in the WorkOS dashboard.

What these issues share in common is a mismatch between local development and production environments in terms of domain names, callback URLs, cookie scope, and related configuration. When the logout redirect URL, allowed callback URLs, or cookie-related settings configured in the dashboard don't match the actual domain in production, the logout flow breaks — the user clicks logout, but the session isn't properly cleared, or the redirect points to the wrong address.

When troubleshooting these issues, the recommended approach is to go through the dashboard's environment-specific configuration items one by one, confirm that your production domain is correctly registered, and verify that the cookie scope settings cover your actual deployed domain. These three configuration items are small, but they're the deciding factor in whether the authentication flow completes cleanly in production.

Summary

Integrating WorkOS AuthKit into a Ruby on Rails application is far more involved than just getting through a login flow once. The real work is in the session layer: understanding what's inside sealed cookies, properly handling session refresh in before_action, and avoiding the console configuration pitfalls that break logout in production. Getting these details right is what separates a polished, production-grade authentication system from one that works only in demos.