Stackd Ruby Client

Codeship Status for stackd/stackd-ruby

Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file lib/stackd. To experiment with that code, run bin/console for an interactive prompt.

TODO: Delete this and the text above, and describe your gem


Add this line to your application's Gemfile:

gem 'stackd'

And then execute:

$ bundle

Or install it yourself as:

$ gem install stackd


Creating a client
$stackd = id: 'YOUR_CLIENT_ID',
                             secret: 'YOUR_CLIENT_SECRET'
Getting an app token
app_token = $stackd.auth_requests.client scope: 'a,b,c'
# => <Stackd::Token app_id: "YOUR_CLIENT_ID",
#                   scope: "a,b,c",
#                   access_token: "e1979b29529ac",
#                   expires_in: 3600>
Getting a user token
class MyController
  def authorize
    auth_request = $ redirect_uri: 'YOUR_CALLBACK_URL',
                                             scope: 'a,b,c'

    session[:auth_state] = auth_request.state

    redirect_to auth_request.url

  def callback
    auth_request = $ state: session[:state]

    user_token = auth_request.callback code: params[:code],
                                       state: params[:state]
    # => <Stackd::Token user_id: "09545bce-3c31-4593-99bd-1dfe8b98df93",
    #                   scope: "a,b",
    #                   access_token: "e1979b29529ac",
    #                   refresh_token: "ca92592b9791e",
    #                   expires_in: 3600>
Refreshing a user token
refreshed_user_token = $stackd.auth_requests.refresh user_token
Persisting tokens (example)
rails generate model TokenData \
  user_id:string \
  scope:string \
  access_token:string \
  refresh_token:string \
Stackd::Token.on_grant do |token|
  TokenData.create! user_id: token.user_id,
                    scope: token.scope,
                    access_token: token.access_token,
                    refresh_token: token.refresh_token,
                    expires_in: token.expires_in
class TokenData
  def self.fresh_token_by criteria
    # ...
    token = $ user_id: user_id,
                               scope: scope,
                               access_token: access_token,
                               refresh_token: refresh_token,
                               expires_in: expires_in,
                               token_type: 'bearer'

    if expired?
      $stackd.auth_requests.refresh token

  def expired? > created_at + expires_in.seconds
Making requests :rappers, name: 'Marshall Mathers'
# POST /rappers
# {"name": "Marshall Mathers"}
# => { ... }
token.patch :rappers, ':id', name: 'EMIN3M'
# PATCH /rappers/:id
# {"name": "EMIN3M"}
# => { ... }
token.get :rapper, ':id'
# GET /rappers/:id
# => { ... }
token.get :rappers, q: 'Slim Shady'
# GET /rappers?q=Slim%20Shady
# => { rappers: [ ... ], ... }
token.get '/any/url'
# GET /any/url

Application errors (4xx)

Will throw a Stackd::Error:

# <Stackd::Error error="error_code"
#                error_description="Something went wrong."
#                error_uri="">

Server errors (5xx)

Will throw a Stackd::ServerError.


After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment. Run bundle exec stackd to use the code located in this directory, ignoring other installed copies of this gem.

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 to create a git tag for the version, push git commits and tags, and push the .gem file to


  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request