README.md in tokenable-ruby-0.1.0 vs README.md in tokenable-ruby-0.2.0
- old
+ new
@@ -1,125 +1,103 @@
# Tokenable
-
+
+[](https://codecov.io/gh/tokenable/tokenable-ruby)
+
+
-Tokenable is a gem for Rails to enable the ability for API applications to provide Authentication.
+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.
-This allows you to provide authentication to mobile apps, or SPAs with ease.
+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'
+gem 'tokenable-ruby', git: 'https://github.com/tokenable/tokenable-ruby.git', branch: 'main'
```
And then execute:
```
bundle install
```
## Usage
-In your `config/routes.rb`, please add:
+Once you have the gem installed, lets get it setup:
-```ruby
-mount Tokenable::Engine => '/api/auth'
+```bash
+rails generate tokenable:install User --strategy=devise
```
-And in your `User` model, please add an Auth Strategy. For example, if you are using `has_secure_password`, then you could use:
+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):
-```ruby
-class User < ApplicationRecord
- include Tokenable::Strategies::SecurePassword
+- [devise](https://github.com/heartcombo/devise)
+- [sorcery](https://github.com/Sorcery/sorcery)
+- [secure_password](https://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html)
- has_secure_password
-end
-```
+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.
-You can chose from:
+### Controllers
-- `Tokenable::Strategies::SecurePassword`
-- `Tokenable::Strategies::Devise`
+To limit access to your controllers/endpoints, you will need to include Tokenable.
-You can also create your own stragery. This is as simple as creating a method on the User object.
-
```ruby
-def self.from_tokenable_params(params)
- user = User.find_by(something: params[:something])
- return nil unless user.present?
+class SomeController < ApplicationController
+ include Tokenable::Authable
- return nil unless user.password_valid?(params[:password])
- user
+ before_action :require_tokenable_user!
end
```
+After you have done this, the following methods are available:
+
+- `current_user`
+- `user_signed_in?`
+
### Invalidate Tokens
-If you want to be able to invalidate tokens from the server, then you can add `Tokenable::Verifier`.
+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:
-```ruby
-class User < ApplicationRecord
- include Tokenable::Verifier
-end
```
+rails generate tokenable:verifier User
+```
-And running the following migration:
+And then run your migrations:
-```bash
-rails g migration AddTokenableVerifierToUsers tokenable_verifier:string
```
+rails db:migrate
+```
You can now invalidate all tokens by calling `user.invalidate_tokens!`.
### Token Expiry
-By default, tokens will live forever. If you want to change this, you can set a config option (see below for how to set that up).
+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
-```
-### Configuration Options
-
-Tokenable works out of the box, with no config required, however you can tweak the settings, by creating `config/initializers/tokenable.rb` file.
-
-```ruby
-# The secret used to create these tokens. This is then used to verify the
-# token is valid. Note: Tokens are not encrypted, and container the user_id.
-# Default: Rails.application.secret_key_base
-Tokenable::Config.secret = 'a-256-bit-string'
+# Tokens will never expire
+Tokenable::Config.lifespan = nil
```
-### Example Usage
+### Example Use Cases
-Once you have this setup, you can login. For example, you could login using `axios` in JavaScript:
+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:
-```js
-const { data } = await axios.post("https://example.com/api/auth", {
- email: "email@example.com",
- password: "coolpassword123",
-});
+- [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)
-const token = data.data.token;
-const user_id = data.data.user_id;
-```
-
-You then use this token in all future API requests:
-
-```js
-const { data } = await axios.get(`https://example.com/api/user/${user_id}`, {
- headers: { Authorization: `Bearer ${token}` },
-});
-```
-
## Development
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies.
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+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](https://github.com/tokenable/tokenable-ruby/blob/main/CODE_OF_CONDUCT.md).