Twitter OAuth2 Client Library in Ruby.
Add this line to your application's Gemfile:
gem 'twitter_oauth2'And then execute:
$ bundle install
Or install it yourself as:
$ gem install twitter_oauth2
In order to use Oauth2 tokens generated by this gem to talk to the Twitter API, your Twitter Developer account needs to be set up as follows:
- Sign up for a twitter developer account (a Free plan is sufficient)
- Create a Project and an App in the Twitter Developer Portal
- Press the Edit button in the User authentication set up section of the Settings tab of your Twitter Developer app
- In the User authentication settings screen:
- Set App Permissions to Read and Write
- Set Type of App to Web App, Automated App or Bot (otherwise, trying to access a token will fail with
invalid_request :: Value passed for the authorization code was invalid. (Rack::OAuth2::Client::Error)) - Set App Info->Callback URI / Redirect URL to any url, noting that when you run the authorization step below, authenticating the token will redirect to that URL and you will need to use the
codequery string parameter that is provided in the redirect to complete this script
- Visit the Keys and tokens tab of your Twitter Developer app
- Generate a Client ID and Client Secret in the OAuth 2.0 Client ID and Client Secret
- That Client ID and Client Secret is used as
<YOUR-CLIENT-ID>and<YOUR-CLIENT-SECRET>in the following Usage example
require 'twitter_oauth2'
client = TwitterOAuth2::Client.new(
identifier: '<YOUR-CLIENT-ID>',
secret: '<YOUR-CLIENT-SECRET>',
redirect_uri: '<YOUR-CALLBACK-URL>'
)
authorization_uri = client.authorization_uri(
scope: [
:'users.read',
:'tweet.read',
:'offline.access'
]
)
# NOTE:
# When `TwitterOAuth2::Client#authorization_uri` is called,
# PKCE `code_verifier` and `state` are automatically generated.
# You can get it here.
code_verifier = client.code_verifier
state = client.state
# When this step runs, you will need to be logged into your
# Twitter developer account in the web browser and you will
# be prompted to authorize. You will then be redirected by
# Twitter to the 'Callback URI / Redirect URL' specified in
# the setup above and that redirection will contain a 'code'
# query string parameter. You will need to copy that code
# and use it in the next part of the script
puts authorization_uri
`open "#{authorization_uri}"`
print 'code: ' and STDOUT.flush
code = gets.chop
# NOTE: Obtaining Access Token & Refresh Token using Authorization Code
client.authorization_code = code
token_response = client.access_token! code_verifier
# NOTE: Refreshing Access Token using Refresh Token
client.refresh_token = token_response.refresh_token
client.access_token!If you want to get App-only Bearer Token (via grant_type=client_credentials), you need some tweaks as below.
require 'twitter_oauth2'
client = TwitterOAuth2::Client.new(
# NOTE: not OAuth 2.0 Client ID, but OAuth 1.0 Consumer Key (a.k.a API Key)
identifier: '<YOUR-CONSUMER-KEY>',
# NOTE: not OAuth 2.0 Client Secret, but OAuth 1.0 Consumer Secret (a.k.a API Key Secret)
secret: '<YOUR-CONSUMER-SECRET>'
# NOTE: Twitter has Client Credentials Grant specific token endpoint.
token_endpoint: '/oauth2/token',
)
client.access_token!For more usage, read the underling gem's wiki.
Once you have an access token from the above script (which you can find by inspecting the access_token property of the token_response variable in the script above before refreshing the token), you can use that token to talk to the Twitter V2 API.
curl --location --request GET 'https://api.twitter.com/2/users/me' \
--header 'Authorization: Bearer <YOUR-ACCESS-TOKEN>'
Free (ie. unpaid) Twitter Developer Accounts] are only allowed to access:
- POST /2/tweets
- DELETE /2/tweets/:id
- GET /2/users/me
If you try to access any other API endpoints, you will see an error like:
{"client_id":"8633235","detail":"When authenticating requests to the Twitter API v2 endpoints, you must use keys and tokens from a Twitter developer App that is attached to a Project. You can create a project via the developer portal.","registration_url":"https://developer.twitter.com/en/docs/projects/overview","title":"Client Forbidden","required_enrollment":"Appropriate Level of API Access","reason":"client-not-enrolled","type":"https://api.twitter.com/2/problems/client-forbidden"}
This gem is built on rack/oauth2 gem.
Basically, the usage is same with the underling gem.
The only difference is that this gem is supporting PKCE as default, since Twitter requires it.
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
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.
Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/twitter_oauth2. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the TwitterOAuth2 project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.