Monzo.Auth (monzo_client v1.0.0)

The OAuth2 authentication flow: building the authorization URL, exchanging a code, refreshing tokens, logging out, and token introspection.

Most applications don't call exchange_code/2 or refresh_token/2 directly - Monzo.Client and its Monzo.TokenStore handle the token lifecycle automatically. This module is here for the initial authorization-code exchange (which necessarily happens before you have a client with tokens) and for advanced manual control.

Summary

Types

authorization_url_params()

exchange_code_params()

refresh_token_params()

Functions

build_authorization_url(params)

Builds the URL to send a user's browser to in order to begin the OAuth2 authorization-code flow.

build_authorization_url!(params)

Same as build_authorization_url/1 but raises on invalid input.

exchange_code(client, params)

Exchanges a temporary authorization code (from the OAuth callback) for an access token. client need not have any tokens configured yet.

logout(client)

Immediately invalidates the client's current access token server-side.

refresh_token(client, params)

Exchanges a refresh token for a new access token. This is a one-time-use operation on the refresh token - Monzo issues a new one alongside the new access token.

who_am_i(client)

Returns metadata about the client's currently configured access token.

Types

authorization_url_params()

@type authorization_url_params() :: %{
  client_id: String.t(),
  redirect_uri: String.t(),
  state: String.t()
}

exchange_code_params()

@type exchange_code_params() :: %{
  client_id: String.t(),
  client_secret: String.t(),
  redirect_uri: String.t(),
  code: String.t()
}

refresh_token_params()

@type refresh_token_params() :: %{
  client_id: String.t(),
  client_secret: String.t(),
  refresh_token: String.t()
}

Functions

build_authorization_url(params)

@spec build_authorization_url(authorization_url_params()) ::
  {:ok, String.t()} | {:error, Monzo.Error.ValidationError.t()}

Builds the URL to send a user's browser to in order to begin the OAuth2 authorization-code flow.

Always generate and persist a random :state value (see Monzo.Security.generate_state/1) and verify it on callback with Monzo.Security.constant_time_equal?/2.

build_authorization_url!(params)

@spec build_authorization_url!(authorization_url_params()) :: String.t()

Same as build_authorization_url/1 but raises on invalid input.

exchange_code(client, params)

@spec exchange_code(Monzo.Client.t(), exchange_code_params()) ::
  {:ok, Monzo.Auth.Token.t()} | {:error, Exception.t()}

Exchanges a temporary authorization code (from the OAuth callback) for an access token. client need not have any tokens configured yet.

logout(client)

@spec logout(Monzo.Client.t()) :: :ok | {:error, Exception.t()}

Immediately invalidates the client's current access token server-side.

refresh_token(client, params)

@spec refresh_token(Monzo.Client.t(), refresh_token_params()) ::
  {:ok, Monzo.Auth.Token.t()} | {:error, Exception.t()}

Exchanges a refresh token for a new access token. This is a one-time-use operation on the refresh token - Monzo issues a new one alongside the new access token.

who_am_i(client)

@spec who_am_i(Monzo.Client.t()) ::
  {:ok, Monzo.Auth.WhoAmI.t()} | {:error, Exception.t()}

Returns metadata about the client's currently configured access token.