OAuth2.Client (OAuth2 v2.1.0) View Source
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"})
Link to this section 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.
Un-register a serialization module for a given mime type.
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
.
Register a serialization module for a given mime type.
Refreshes an existing access token using a refresh token.
Calls refresh_token/4
but raises Error
if there an error occurs.
Link to this section Types
Specs
authorize_url() :: binary()
Specs
body() :: any()
Specs
client_id() :: binary()
Specs
client_secret() :: binary()
Specs
Specs
Specs
Specs
redirect_uri() :: binary()
Specs
ref() :: reference() | nil
Specs
request_opts() :: Keyword.t()
Specs
Specs
site() :: binary()
Specs
strategy() :: module()
Specs
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(), serializers: serializers(), site: site(), strategy: strategy(), token: token(), token_method: token_method(), token_url: token_url() }
Specs
token() :: OAuth2.AccessToken.t() | nil
Specs
token_method() :: :post | :get | atom()
Specs
token_url() :: binary()
Link to this section Functions
Specs
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"
Specs
Adds authorization
header for basic auth.
Specs
delete(t(), binary(), body(), headers(), Keyword.t()) :: {:ok, OAuth2.Response.t()} | {:error, OAuth2.Response.t()} | {:error, OAuth2.Error.t()}
Makes a DELETE
request to the given URL using the OAuth2.AccessToken
.
Specs
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}
).
Specs
Un-register a serialization module for a given mime type.
Example
iex> client = OAuth2.Client.delete_serializer(%OAuth2.Client{}, "application/json")
%OAuth2.Client{}
iex> OAuth2.Client.get_serializer(client, "application/json")
nil
Specs
get(t(), binary(), headers(), Keyword.t()) :: {:ok, OAuth2.Response.t()} | {:error, OAuth2.Response.t()} | {:error, OAuth2.Error.t()}
Makes a GET
request to the given url
using the OAuth2.AccessToken
struct.
Specs
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.
Specs
get_token(t(), params(), headers(), Keyword.t()) :: {:ok, t()} | {:error, OAuth2.Response.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 depending 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
Specs
Same as get_token/4
but raises OAuth2.Error
if an error occurs during the
request.
Specs
Set multiple params in the client in one call.
Specs
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"}
Specs
patch(t(), binary(), body(), headers(), Keyword.t()) :: {:ok, OAuth2.Response.t()} | {:error, OAuth2.Response.t()} | {:error, OAuth2.Error.t()}
Makes a PATCH
request to the given url
using the OAuth2.AccessToken
struct.
Specs
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}
).
Specs
post(t(), binary(), body(), headers(), Keyword.t()) :: {:ok, OAuth2.Response.t()} | {:error, OAuth2.Response.t()} | {:error, OAuth2.Error.t()}
Makes a POST
request to the given URL using the OAuth2.AccessToken
.
Specs
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}
).
Specs
put(t(), binary(), body(), headers(), Keyword.t()) :: {:ok, OAuth2.Response.t()} | {:error, OAuth2.Response.t()} | {:error, OAuth2.Error.t()}
Makes a PUT
request to the given url
using the OAuth2.AccessToken
struct.
Specs
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}
).
Specs
Adds a new header key
if not present, otherwise replaces the
previous value of that header with value
.
Specs
Set multiple headers in the client in one call.
Specs
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.
Specs
Register a serialization module for a given mime type.
Example
iex> client = OAuth2.Client.put_serializer(%OAuth2.Client{}, "application/json", Jason)
%OAuth2.Client{serializers: %{"application/json" => Jason}}
iex> OAuth2.Client.get_serializer(client, "application/json")
Jason
Specs
refresh_token(t(), params(), headers(), Keyword.t()) :: {:ok, t()} | {:error, OAuth2.Response.t()} | {:error, OAuth2.Error.t()}
Refreshes an existing access token using a refresh token.
Specs
Calls refresh_token/4
but raises Error
if there an error occurs.