OAuth2 v0.9.2 OAuth2.Client
This module defines the OAuth2.Client
struct and is responsible for building
and establishing a request for an access token.
Notes
If a full url is given (e.g. “http://www.example.com/api/resource”) then it will use that otherwise you can specify an endpoint (e.g. “/api/resource”) and it will append it to the
Client.site
.The headers from the
Client.headers
are appended to the request headers.
Examples
client = OAuth2.Client.new(token: "abc123")
case OAuth2.Client.get(client, "/some/resource") do
{:ok, %OAuth2.Response{body: body}} ->
"Yay!!"
{:error, %OAuth2.Response{body: body}} ->
"Something bad happen: #{inspect body}"
{:error, %OAuth2.Error{reason: reason}} ->
reason
end
response = OAuth2.Client.get!(client, "/some/resource")
response = OAuth2.Client.post!(client, "/some/other/resources", %{foo: "bar"})
Summary
Functions
Returns the authorize url based on the client configuration
Adds authorization
header for basic auth
Makes a DELETE
request to the given URL using the OAuth2.AccessToken
Same as delete/5
but returns a OAuth2.Response
or OAuth2.Error
exception
if the request results in an error
Makes a GET
request to the given url
using the OAuth2.AccessToken
struct
Same as get/4
but returns a OAuth2.Response
or OAuth2.Error
exception if
the request results in an error
Fetches an OAuth2.AccessToken
struct by making a request to the token endpoint
Same as get_token/4
but raises OAuth2.Error
if an error occurs during the
request
Set multiple params in the client in one call
Builds a new OAuth2.Client
struct using the opts
provided
Makes a PATCH
request to the given url
using the OAuth2.AccessToken
struct
Same as patch/5
but returns a OAuth2.Response
or OAuth2.Error
exception if
the request results in an error
Makes a POST
request to the given URL using the OAuth2.AccessToken
Same as post/5
but returns a OAuth2.Response
or OAuth2.Error
exception
if the request results in an error
Makes a PUT
request to the given url
using the OAuth2.AccessToken
struct
Same as put/5
but returns a OAuth2.Response
or OAuth2.Error
exception if
the request results in an error
Adds a new header key
if not present, otherwise replaces the
previous value of that header with value
Set multiple headers in the client in one call
Puts the specified value
in the params for the given key
Refreshes an existing access token using a refresh token
Calls refresh_token/4
but raises Error
if there an error occurs
Types
t() :: %OAuth2.Client{authorize_url: authorize_url, client_id: client_id, client_secret: client_secret, headers: headers, params: params, redirect_uri: redirect_uri, ref: ref, request_opts: request_opts, site: site, strategy: strategy, token: token, token_method: token_method, token_url: token_url}
Functions
Returns the authorize url based on the client configuration.
Example
iex> OAuth2.Client.authorize_url!(%OAuth2.Client{})
"/oauth/authorize?client_id=&redirect_uri=&response_type=code"
delete(t, binary, body, headers, Keyword.t) :: {:ok, OAuth2.Response.t} | {:error, OAuth2.Error.t}
Makes a DELETE
request to the given URL using the OAuth2.AccessToken
.
delete!(t, binary, body, headers, Keyword.t) :: OAuth2.Response.t | OAuth2.Error.t
Same as delete/5
but returns a OAuth2.Response
or OAuth2.Error
exception
if the request results in an error.
An OAuth2.Error
exception is raised if the request results in an
error tuple ({:error, reason}
).
get(t, binary, headers, Keyword.t) :: {:ok, OAuth2.Response.t} | {:error, OAuth2.Error.t}
Makes a GET
request to the given url
using the OAuth2.AccessToken
struct.
get!(t, binary, headers, Keyword.t) :: OAuth2.Response.t | OAuth2.Error.t
Same as get/4
but returns a OAuth2.Response
or OAuth2.Error
exception if
the request results in an error.
get_token(t, params, headers, Keyword.t) :: {:ok, OAuth2.Client.t} | {:error, OAuth2.Error.t}
Fetches an OAuth2.AccessToken
struct by making a request to the token endpoint.
Returns the OAuth2.Client
struct loaded with the access token which can then
be used to make authenticated requests to an OAuth2 provider’s API.
Arguments
client
- aOAuth2.Client
struct with the strategy to use, defaults toOAuth2.Strategy.AuthCode
params
- a keyword list of request parameters which will be encoded into a query string or request body dependening on the selected strategyheaders
- a list of request headersopts
- a Keyword list of request options which will be merged withOAuth2.Client.request_opts
Options
:recv_timeout
- the timeout (in milliseconds) of the request:proxy
- a proxy to be used for the request; it can be a regular url or a{host, proxy}
tuple
get_token!(t, params, headers, Keyword.t) :: OAuth2.Client.t | OAuth2.Error.t
Same as get_token/4
but raises OAuth2.Error
if an error occurs during the
request.
Set multiple params in the client in one call.
Builds a new OAuth2.Client
struct using the opts
provided.
Client struct fields
authorize_url
- absolute or relative URL path to the authorization endpoint. Defaults to"/oauth/authorize"
client_id
- the client_id for the OAuth2 providerclient_secret
- the client_secret for the OAuth2 providerheaders
- a list of request headersparams
- a map of request parametersredirect_uri
- the URI the provider should redirect to after authorization or token requestsrequest_opts
- a keyword list of request options that will be sent to thehackney
client. See the hackney documentation for a list of available options.site
- the OAuth2 provider site hoststrategy
- a module that implements the appropriate OAuth2 strategy, defaultOAuth2.Strategy.AuthCode
token
-%OAuth2.AccessToken{}
struct holding the token for requests.token_method
- HTTP method to use to request token (:get
or:post
). Defaults to:post
token_url
- absolute or relative URL path to the token endpoint. Defaults to"/oauth/token"
Example
iex> OAuth2.Client.new(token: "123")
%OAuth2.Client{authorize_url: "/oauth/authorize", client_id: "",
client_secret: "", headers: [], params: %{}, redirect_uri: "", site: "",
strategy: OAuth2.Strategy.AuthCode,
token: %OAuth2.AccessToken{access_token: "123", expires_at: nil,
other_params: %{}, refresh_token: nil, token_type: "Bearer"},
token_method: :post, token_url: "/oauth/token"}
iex> token = OAuth2.AccessToken.new("123")
iex> OAuth2.Client.new(token: token)
%OAuth2.Client{authorize_url: "/oauth/authorize", client_id: "",
client_secret: "", headers: [], params: %{}, redirect_uri: "", site: "",
strategy: OAuth2.Strategy.AuthCode,
token: %OAuth2.AccessToken{access_token: "123", expires_at: nil,
other_params: %{}, refresh_token: nil, token_type: "Bearer"},
token_method: :post, token_url: "/oauth/token"}
patch(t, binary, body, headers, Keyword.t) :: {:ok, OAuth2.Response.t} | {:error, OAuth2.Error.t}
Makes a PATCH
request to the given url
using the OAuth2.AccessToken
struct.
patch!(t, binary, body, headers, Keyword.t) :: OAuth2.Response.t | OAuth2.Error.t
Same as patch/5
but returns a OAuth2.Response
or OAuth2.Error
exception if
the request results in an error.
An OAuth2.Error
exception is raised if the request results in an
error tuple ({:error, reason}
).
post(t, binary, body, headers, Keyword.t) :: {:ok, OAuth2.Response.t} | {:error, OAuth2.Error.t}
Makes a POST
request to the given URL using the OAuth2.AccessToken
.
post!(t, binary, body, headers, Keyword.t) :: OAuth2.Response.t | OAuth2.Error.t
Same as post/5
but returns a OAuth2.Response
or OAuth2.Error
exception
if the request results in an error.
An OAuth2.Error
exception is raised if the request results in an
error tuple ({:error, reason}
).
put(t, binary, body, headers, Keyword.t) :: {:ok, OAuth2.Response.t} | {:error, OAuth2.Error.t}
Makes a PUT
request to the given url
using the OAuth2.AccessToken
struct.
put!(t, binary, body, headers, Keyword.t) :: OAuth2.Response.t | OAuth2.Error.t
Same as put/5
but returns a OAuth2.Response
or OAuth2.Error
exception if
the request results in an error.
An OAuth2.Error
exception is raised if the request results in an
error tuple ({:error, reason}
).
Adds a new header key
if not present, otherwise replaces the
previous value of that header with value
.
Puts the specified value
in the params for the given key
.
The key can be a string
or an atom
. Atoms are automatically
convert to strings.
refresh_token(t, params, headers, Keyword.t) :: {:ok, OAuth2.Client.t} | {:error, OAuth2.Error.t}
Refreshes an existing access token using a refresh token.
refresh_token!(t, params, headers, Keyword.t) :: OAuth2.Client.t | OAuth2.Error.t
Calls refresh_token/4
but raises Error
if there an error occurs.