goth

v1.2.0

goth v1.2.0 Goth.Token

Interface for retrieving access tokens, from either the Goth.TokenStore or the Google token API. The first request for a token will hit the API, but subsequent requests will retrieve the token from Goth's token store.

Goth will automatically refresh access tokens in the background as necessary, 10 seconds before they are to expire. After the initial synchronous request to retrieve an access token, your application should never have to wait for a token again.

The first call to retrieve an access token for a particular scope blocks while it hits the API. Subsequent calls pull from the Goth.TokenStore, and should return immediately

iex> Goth.Token.for_scope("https://www.googleapis.com/auth/pubsub")
{:ok, %Goth.Token{token: "23984723",
                  type: "Bearer",
                  scope: "https://www.googleapis.com/auth/pubsub",
                  expires: 1453653825,
                  account: :default}}

If the passed credentials contain multiple service account, you can change the first parametter to be {client_email, scopes} to specify which account to target.

iex> Goth.Token.for_scope({"myaccount@project.iam.gserviceaccount.com", "https://www.googleapis.com/auth/pubsub"})
{:ok, %Goth.Token{token: "23984723",
                  type: "Bearer",
                  scope: "https://www.googleapis.com/auth/pubsub",
                  expires: 1453653825,
                  account: "myaccount@project.iam.gserviceaccount.com"}}

For using the token on subsequent requests to the Google API, just concatenate the type and token to create the authorization header. An example using HTTPoison:

{:ok, token} = Goth.Token.for_scope("https://www.googleapis.com/auth/pubsub")
HTTPoison.get(url, [{"Authorization", "#{token.type} #{token.token}"}])

Link to this section Summary

Types

t()

Functions

for_scope(info, sub \\ nil)

Get a %Goth.Token{} for a particular scope. scope can be a single scope or multiple scopes joined by a space. See OAuth 2.0 Scopes for Google APIs for all available scopes

from_response_json(scope, sub \\ nil, json)

Parse a successful JSON response from Google's token API and extract a %Goth.Token{}

queue_for_refresh(token)
refresh!(token)

Retrieve a new access token from the API. This is useful for expired tokens, although Goth automatically handles refreshing tokens for you, so you should rarely if ever actually need to call this method manually

refresh!(arg, sub \\ nil)

Link to this section Types

Link to this type

t() 
t() :: %Goth.Token{
  account: String.t(),
  expires: non_neg_integer(),
  scope: String.t(),
  sub: String.t() | nil,
  token: String.t(),
  type: String.t()
}

Link to this section Functions

Link to this function

for_scope(info, sub \\ nil) 
for_scope(scope :: String.t(), sub :: String.t() | nil) ::
  {:ok, t()} | {:error, any()}
for_scope(info :: {String.t() | atom(), String.t()}, sub :: String.t() | nil) ::
  {:ok, t()} | {:error, any()}

Get a %Goth.Token{} for a particular scope. scope can be a single scope or multiple scopes joined by a space. See OAuth 2.0 Scopes for Google APIs for all available scopes.

sub needs to be specified if impersonation is used to prevent cache leaking between users.

Example 

iex> Token.for_scope("https://www.googleapis.com/auth/pubsub")
{:ok, %Goth.Token{expires: ..., token: "...", type: "..."} }
Link to this function

from_response_json(scope, sub \\ nil, json) 
from_response_json(String.t(), String.t() | nil, String.t()) :: t()
from_response_json(
  {atom() | String.t(), String.t()},
  String.t() | nil,
  String.t()
) :: t()

Parse a successful JSON response from Google's token API and extract a %Goth.Token{}

Link to this function

queue_for_refresh(token)

Link to this function

refresh!(token) 
refresh!(t() | {any(), any()}) :: {:ok, t()}

Retrieve a new access token from the API. This is useful for expired tokens, although Goth automatically handles refreshing tokens for you, so you should rarely if ever actually need to call this method manually.

Link to this function

refresh!(arg, sub \\ nil) 
refresh!({any(), any()}, any()) :: {:ok, t()}