Tokenable

Tokenable is a Rails gem that allows API-only applications a way to authenticate users. This can be helpful when building Single Page Applications, or Mobile Applications. It's designed to work with the auth system you are already using, such as Devise, Sorcery and has_secure_password. You can also use it with any custom auth systems.

Simply send a login request to the authentication endpoint, and Tokenable will return a token. This token can then be used to access your API, and any authenticated endpoints.

Installation

Add this line to your application's Gemfile:

gem 'tokenable-ruby'

And then execute:

bundle install

Usage

Once you have the gem installed, lets get it setup:

rails generate tokenable:install User --strategy=devise

We make it easier for you, by adding out of the box support for some auth libraries. You can pick from the following options for --strategy, or leave it empty for a custom strategy:

• devise
• sorcery
• secure_password

This will add a route, the configuration file at config/initializers/tokenable.rb, and add the required includes to your User model. There are no migrations to run in the default configuration.

Controllers

To limit access to your controllers/endpoints, you will need to include Tokenable.

class SomeController < ApplicationController
  include Tokenable::Authable

  before_action :require_tokenable_user!
end

After you have done this, the following methods are available:

• current_user
• user_signed_in?

Invalidate Tokens

Sometime you want to be able to force a user (or users) to login again. You can do this by adding the Verifier. To install this, run:

rails generate tokenable:verifier User

And then run your migrations:

rails db:migrate

You can now invalidate all tokens by calling user.invalidate_tokens!.

Token Expiry

By default, tokens expire after 7 days. If you want to change this, you can set a config option.

# Expire in 7 days (default)
Tokenable::Config.lifespan = 7.days

# Tokens will never expire
Tokenable::Config.lifespan = nil

Example Use Cases

Once you have this setup, you will then be able to integrate your Rails API with a mobile app, single page application, or any other type of system. Here are some example use cases:

• Using Tokenable with Nuxt.js Auth
• Using Tokenable with Axios
• Using Tokenable with Curl

Development

After checking out the repo, run bin/setup to install dependencies.

Then, run bundle exec rspec to run the tests.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/tokenable/tokenable-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Tokenable project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.