Retrieves an access token from an OAuth2 provider using the supplied credentials.

gem install access_token_agent -v 3.5.0


Gem Version


Handles authentication against an OAuth2 provider.

Retrieves an access token from the authentication server using the OAuth2 client credentials flow.


Add this line to your application's Gemfile:

gem 'access_token_agent', '~> 3.4'

And then execute:

$ bundle

Basic configuration

Create an instance of AccessTokenAgent::Connector with the desired configuration and use that instance to authenticate.

Needs the following parameters to instantiate:

  • host - the server address where the auth provider is running.
  • client_id - the client_id of the application using this gem.
  • client_secret - the client_secret of the application using this gem.

Optional parameters:

  • fake_auth - if true, do not connect to the auth service and return a faked access token.
  • access_token_path - Allows to customize the HTTP path where the access token needs to be requested. Default: /oauth/token
  • scopes - An array of scopes to be requested from the authorization server Default: no scopes


@connector = '',
                                             client_id: 'my_client',
                                             client_secret: 'very_secure_and_secret')

Sharing a connector

When connecting to multiple endpoints you will commonly come across the need to share a single instance of a connector in multiple places, because your application will use the same configuration everywhere.

You can use the convenience accessor instance for that:

AccessTokenAgent::Connector.instance =


Set up an AcccessTokenAgent::Connector instance (see Configuration) and call authenticate on it to receive your access_token.

 => "XYZ"

When no valid AccessToken is present a call to authenticate returns one of the following:

  • a Bearer Token if the credentials are valid (auth response code 200)
  • raises an UnauthorizedError if the credentials are invalid (auth response code 401)
  • raises an Error if the auth response code is neither 200 nor 401

As long as a valid AccessToken is present a call to authenticate simply returns that AccessToken. An AccessToken is valid for a limited time. The exact value is determined by the auth response which contains an expires_at parameter.

As HTTP Header

Since the most common use case is to include the access token as RFC 6750 bearer token, there is a method that returns the Authorization: Bearer XYZ header as hash:

 => { "Authorization" => "Bearer XYZ" }