https://github.com/tokenable/tokenable-ruby
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. Works with Devise, Sorcery, has_secure_password, and any other auth system you may want to use.
https://github.com/tokenable/tokenable-ruby
api authentification rails
Last synced: 7 months ago
JSON representation
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. Works with Devise, Sorcery, has_secure_password, and any other auth system you may want to use.
- Host: GitHub
- URL: https://github.com/tokenable/tokenable-ruby
- Owner: tokenable
- License: mit
- Created: 2021-01-16T13:07:59.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2023-12-04T15:38:52.000Z (about 2 years ago)
- Last Synced: 2025-07-27T05:28:19.863Z (7 months ago)
- Topics: api, authentification, rails
- Language: Ruby
- Homepage:
- Size: 93.8 KB
- Stars: 13
- Watchers: 1
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Tokenable
[](https://badge.fury.io/rb/tokenable-ruby)
[](https://codecov.io/gh/tokenable/tokenable-ruby)
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:
```ruby
gem 'tokenable-ruby'
```
And then execute:
```
bundle install
```
## Usage
Once you have the gem installed, lets get it setup:
```bash
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](https://github.com/tokenable/tokenable-ruby/wiki/Create-your-own-statergy):
- [devise](https://github.com/heartcombo/devise)
- [sorcery](https://github.com/Sorcery/sorcery)
- [secure_password](https://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html)
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.
```ruby
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.
```ruby
# 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](https://github.com/tokenable/tokenable-ruby/wiki/Integration-with-Nuxt.js-Auth)
- [Using Tokenable with Axios](https://github.com/tokenable/tokenable-ruby/wiki/Integration-with-Axios)
- [Using Tokenable with Curl](https://github.com/tokenable/tokenable-ruby/wiki/Curl-Example)
## 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 . This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/tokenable/tokenable-ruby/blob/main/CODE_OF_CONDUCT.md).
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
## 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](https://github.com/tokenable/tokenable-ruby/blob/main/CODE_OF_CONDUCT.md).