twitch_oauth2

TwitchOAuth2

Twitch authentication with OAuth 2. Result tokens can be used for API libraries, chat libraries or something else.

Twitch Authentication Documentation

Installation

Add this line to your application's Gemfile:

gem 'twitch_oauth2'

And then execute:

bundle install

Or install it yourself as:

gem install twitch_oauth2

Usage

Since version 0.5.0, the main object here is TwitchOAuth2::Tokens which receives and internally uses client for necessary requests. This approach allows:

• get an actual access_token with validations, refreshing and other things inside;
• share and reuse an instance of this class, for example between API and IRC clients;
• initialize 2 instances for user token and application token, but with the same client object.

Initialization

Client, for requests:

require 'twitch_oauth2'

client = TwitchOAuth2::Client.new(
  client_id: 'application_client_id',
  client_secret: 'application_client_secret',
  redirect_uri: 'application_redirect_uri' # default is `http://localhost`
)

Tokens, for their storage and refreshing:

tokens = TwitchOAuth2::Tokens.new(
  client: client, # initialized above, or can be a `Hash` with values for `Client` initialization
  # all other arguments are optional
  access_token: 'somewhere_received_access_token', # default is `nil`
  refresh_token: 'refresh_token_from_the_same_place', # default is `nil`
  token_type: :user, # default is `:application`
  scopes: %w[user:read:email bits:read] # default is `nil`, but it's not so useful
)

Check tokens

Please, use Tokens#valid? method after initialization, especially for empty initial tokens, especially for User Access Token.

If method returned false — direct user to tokens#authorize_link.

For a web-application with N users, you can use :redirect_uri argument for Client initialization as your application callback and redirect them to #authorize_link.

For something like a CLI tool you can print instructions for user with received link.

Application Access Token

It's simpler, has less permissions, and it's the default :token_type.

Application Access Tokens have no refresh_token right now and have longer life time, so the logic here is simpler: you can pass nothing to Tokens.new — the client will generate new access_token, and regenerate when it's will be outdated.

User Access Token

If you need for :user token and you have no actual access_token or refresh_token (checkable by Tokens#valid?), you have to direct user to tokens#authorize_link.

After successful user login there will be redirect from Twitch to the :redirect_uri (by default is localhost) with the code query argument. You have to pass it to the Tokens#code= for access_token and refresh_token generation, they will be available right after it.

It's one-time manual operation for User Access Token, further the gem will give you actual tokens and refresh them as necessary (right now refresh_token, getting after code, has no life time).

Without checking tokens the TwitchOAuth2::AuthorizeError will be raised on #access_token call, and it can interrupt some operations, like API library initialization.

The reference for such behavior is the official Google API gem.

Another reference, twitch package for JavaScript, has refreshing logic, but requires initial correct tokens from you, and doesn't care how you'll get them.

Get tokens

The main method is Tokens#access_token: it's used in API libraries, in chat libraries, etc.

It has refreshing logic inside for cases when it's outdated. But if there is no initial refresh_token — be aware and read the documentation below.

There is also #refresh_token getter, just for storing it or something else, it's more important internally.

Reusing tokens

Then, or if you pass tokens to initialization, client will validate them and return themselves or refresh and return new ones.

Development

After checking out the repo, run bundle install to install dependencies.

Then, run toys rspec to run the tests.

To install this gem onto your local machine, run toys gem install.

To release a new version, run toys gem release %version%. See how it works here.

Contributing

Bug reports and pull requests are welcome on GitHub.

License

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