Open-source project
lynndylanhurley/devise_token_auth avatar
lynndylanhurley/devise_token_auth

devise_token_auth: token authentication for Rails JSON APIs

Token based authentication for Rails JSON APIs. Designed to work with jToker and ng-token-auth.

3,570 stars1,122 forksRubyWTFPL

At a glance

What is it?
devise_token_auth gives Rails JSON APIs token-based authentication built on Devise and OmniAuth, with a session per client device. Here is what the README and repository show, where it fits, and what to check before adopting it.
Who is it for?
Adopt devise_token_auth when you are building a Rails JSON API for a SPA or mobile client and you want Devise's email flows reused as token endpoints, with one session per device. Do not adopt it if you need stateless JWT verification without a database lookup, or if your API is not Rails.
Can I use it commercially?
Yes. WTFPL is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 107 days ago.
What is it written in?
Mainly Ruby, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • lynndylanhurley/devise_token_auth3,570 ★ · +0
Star history
Repository2026-09-242026-11-15
lynndylanhurley/devise_token_auth3.6k3.6k

0 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The problem devise_token_auth solves for Rails JSON APIs

A Rails app that serves a single-page app or a mobile client cannot rely on cookies the way a server-rendered app does. The README frames the choice directly: "If you're building SPA or a mobile app, and you want authentication, you need tokens, not cookies." devise_token_auth is the gem that supplies those tokens while keeping Devise's existing email flows. Registration, update, deletion, login, logout, password reset and account confirmation all stay, but they are exposed as endpoints a JSON client can call rather than as HTML forms.

The second problem it addresses is multi-client sessions. A user signed in on a phone and a laptop should be able to log out of one without ending the other. The README states that the gem "maintains a session for each client/device, so you can have as many sessions as you want." That is a different model from a single session cookie, and it is the reason the gem stores per-client state rather than one token per user.

The audience is narrow on purpose. You need a Rails API and a client that speaks tokens. The README lists first-party integrations for ng-token-auth (AngularJS), Angular-Token, redux-token-auth (React with Redux), jToker (jQuery), vanilla-token-auth and flutter_token_auth. If your front end is not on that list, the gem still works, but you write the client half yourself.

How token refresh and per-device sessions work

The mechanism the README describes is token rotation on every request. Tokens are refreshed as requests come in and expire after a short window, which limits how long a stolen token stays useful. This is not a stateless scheme. Rotation implies server-side state that records which token is currently valid for a given client, and the per-device session model implies that state is keyed per client, not per user. The practical consequence is a lookup on each authenticated request, which is the trade-off you accept in exchange for short expiry and independent logout per device.

On the identity side, the gem builds on two existing libraries. Devise handles email authentication, and OmniAuth handles OAuth2. The README says the project "leverages the following gems: Devise, OmniAuth." So the token layer sits on top of Devise's user model rather than replacing it, and OAuth2 providers are wired through OmniAuth. The repository also documents support for multiple user models, in docs/usage/multiple_models.md, which matters if your API authenticates more than one kind of account.

The README points to docs/security.md for the security model, and that file is part of the repository tree. What the README itself does not give is a written description of the token format or the storage columns. If you need to know exactly what is stored per client before you adopt it, that detail lives in the docs directory, not in the README.

Installing devise_token_auth and making a first request

The README's installation section is two steps. Add the gem to your Gemfile, then run bundle install. The README gives exactly this:

ruby
gem 'devise_token_auth'
bash
bundle install

That is the whole of the install instructions in the README. There is no generator command, no migration command and no initializer snippet in the README text. The README sends you to the documentation site at https://devise-token-auth.gitbook.io/devise-token-auth for the rest, and the repository has a docs/ directory alongside a SUMMARY.md, which is the GitBook table of contents. The repository also ships a config/ directory and an app/ directory, which is where the engine's controllers and configuration live, but the README does not walk through wiring them into a host app.

A working reference exists: the README links a fully configured API at https://github.com/lynndylanhurley/devise_token_auth_demo, and a live demo running with Angular-Token. If you are starting from nothing, that demo repository is the concrete example the project itself offers, because the README stops at bundle install.

For the client side, the README lists several options. The unopinionated one is vanilla-token-auth, described as being "for an unopinionated client." Pick the client library that matches your front end, or write the request headers yourself against the endpoints the docs site describes.

Where devise_token_auth is the wrong tool

The clearest limitation is that this is a Rails gem. It integrates with Devise and OmniAuth, both Ruby libraries, and the repository is a Ruby engine with app/, config/ and lib/ directories. If your API is not Rails, nothing here applies. Even inside Rails, the gem assumes Devise is an acceptable dependency. Teams that have deliberately avoided Devise, or that run a non-ActiveRecord user store, are pushing against the grain of the design.

The second limitation follows from token rotation. Because tokens are refreshed on each request and expire quickly, the server holds session state per client. That is a real cost at scale, and it means you cannot verify a token in isolation the way a self-contained JWT allows. If your architecture requires stateless verification at the edge, or services outside Rails that must validate a token without calling back to the Rails app, this gem's model does not fit. A JWT library used directly with Devise is the shape of that alternative, and the related searches show people comparing the two.

The third gap is documentation depth in the README itself. Installation is one gem line and a bundle install. Everything else lives on the GitBook site or in docs/. The README also states that support requests belong on StackOverflow, and that GitHub issues are for bugs and enhancements only. That is a reasonable policy, but it means the README is not a troubleshooting guide.

devise_token_auth compared with Devise plus a JWT library

The alternative people reach for is Devise paired with a JWT library, usually called Devise-jwt in the searches that surround this project. The difference is where session state lives. devise_token_auth, as its README describes it, refreshes tokens on each request, expires them quickly, and keeps a session per client device. That gives you a revocation list by construction: logging out one device is a server-side operation on that device's session.

A JWT approach inverts this. The token carries its own claims and is verified with a key, so the server does not need to look up a session on every request. That is cheaper per request and works across services that share the key. The cost is revocation. A JWT that has not expired remains valid until it does, unless you add a denylist, which reintroduces the server-side lookup you were avoiding.

So the choice is not about which is more modern. It is about whether you want per-device logout and short expiry handled for you by the gem, with a database read per request, or whether you want stateless verification and you take on revocation yourself. devise_token_auth also brings OmniAuth OAuth2 and the full set of Devise email flows, which a bare JWT setup does not include. If you only need a token and you already handle password reset and confirmation elsewhere, the gem is more than you asked for.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-07-31. That is recent enough that the project is receiving changes, but the README does not describe a release cadence, and the repository has no published releases. The README does say the project wants contributors, links Contribution Guidelines, and mentions bounties on some open issues, which suggests maintainer time is a known constraint. The CHANGELOG.md at the repository root is where version history lives; the README does not summarise it.

Upgrade cost is tied to the dependency chain. Because the gem builds on Devise and OmniAuth, a major Devise or OmniAuth change can force a devise_token_auth upgrade even if you changed nothing. The repository includes an Appraisals file and a gemfiles/ directory, which is the standard pattern for testing against multiple dependency versions, so compatibility work is part of the project's routine. The README does not state which Ruby or Rails versions are supported; check Appraisals and the gemspec before committing.

The licence is the WTFPL. That is a permissive, very short licence, and it is worth reading in full because its wording is unusual compared with MIT or Apache-2.0. Nothing here is legal advice; if your organisation has a licence allowlist, confirm the WTFPL is on it before you ship.

Editorial conclusion

Adopt devise_token_auth when you are building a Rails JSON API for a SPA or mobile client and you want Devise's email flows reused as token endpoints, with one session per device. Do not adopt it if you need stateless JWT verification without a database lookup, or if your API is not Rails. Before starting, read docs/security.md and the multiple_models guide, and confirm which Ruby and Rails versions the Appraisals file covers, because the README does not state them.

Frequently asked questions

What is devise_token_auth?

It is a Ruby gem that adds token-based authentication to Rails JSON APIs. It builds on Devise for email authentication and OmniAuth for OAuth2, and the README describes it as maintaining a session for each client or device.

How do I install devise_token_auth in a Rails app?

The README gives two steps: add gem 'devise_token_auth' to your Gemfile, then run bundle install. The README does not include generator or migration commands, and points to the documentation site for the rest.

Which JavaScript clients work with devise_token_auth?

The README lists ng-token-auth for AngularJS, Angular-Token for Angular, redux-token-auth for React with Redux, jToker for jQuery, vanilla-token-auth as an unopinionated client, and flutter_token_auth for Flutter.

Where should I ask for help with devise_token_auth?

The README asks that help requests and how-to questions go to StackOverflow under the devise-token-auth tag. GitHub issues are reserved for bugs and enhancements, and the README asks you to read the issue template before posting.

What licence does devise_token_auth use?

The README states that the project uses the WTFPL. The LICENSE file is at the repository root.

Official sources

  1. Issues
  2. License: WTFPL
  3. lynndylanhurley/devise_token_auth on GitHub
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/lynndylanhurley-devise-token-auth.svg)](https://hysenlabs.com/projects/lynndylanhurley-devise-token-auth)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/lynndylanhurley-devise-token-auth.svg)](https://hysenlabs.com/projects/lynndylanhurley-devise-token-auth)

Was this useful?