MoneyHub.Config (MoneyHub v1.0.0)

Configuration for a MoneyHub API client.

A MoneyHub.Config struct carries everything needed to talk to the Moneyhub Open Finance API: which environment to use, the OAuth2 client identity, and the key material used to authenticate that client.

Environments

Moneyhub exposes (at least) two environments:

:production - https://identity.moneyhub.co.uk / https://api.moneyhub.co.uk
:sandbox - Moneyhub's test environment, used with mock banks during development. Moneyhub provisions the exact host for this per-client; pass :identity_url / :api_url explicitly if your sandbox host differs from the default.

Client authentication

Moneyhub's token endpoint supports two client authentication methods:

private_key_jwt (recommended, required in production) - the client signs a JWT assertion with its own private key. Configure this with :jwk (a JOSE JWK map/struct) and :jwk_kid.
client_secret_basic (sandbox/early development only) - HTTP Basic auth with :client_id / :client_secret.

Example

config = MoneyHub.Config.new!(
  environment: :sandbox,
  client_id: "abc123",
  jwk: MoneyHub.Auth.PrivateKeyJWT.load_jwk!("priv/keys/sandbox.pem"),
  jwk_kid: "sandbox-signing-key-1"
)

Summary

Types

environment()

t()

Functions

new(opts)

Builds a new t/0, returning {:ok, config} or {:error, reason}.

new!(opts)

Builds a new t/0, raising ArgumentError on invalid options.

Types

environment()

@type environment() :: :production | :sandbox

t()

@type t() :: %MoneyHub.Config{
  api_url: String.t(),
  client_id: String.t(),
  client_secret: String.t() | nil,
  environment: environment(),
  finch_pool: atom(),
  http_options: keyword(),
  identity_url: String.t(),
  jwk: map() | nil,
  jwk_kid: String.t() | nil,
  redirect_uri: String.t() | nil,
  token_endpoint_auth_method: :private_key_jwt | :client_secret_basic
}

Functions

new(opts)

@spec new(keyword()) :: {:ok, t()} | {:error, MoneyHub.Error.t()}

Builds a new t/0, returning {:ok, config} or {:error, reason}.

new!(opts)

@spec new!(keyword()) :: t()

Builds a new t/0, raising ArgumentError on invalid options.

Options

:environment - :production or :sandbox. Defaults to :production.
:client_id - required. The OAuth2 client_id issued by Moneyhub.
:client_secret - required only when :token_endpoint_auth_method is :client_secret_basic.
:jwk - required when :token_endpoint_auth_method is :private_key_jwt (the default). A JOSE JWK as a map or JOSE.JWK struct - see MoneyHub.Auth.PrivateKeyJWT.
:jwk_kid - the kid to embed in signed JWT headers. Required alongside :jwk.
:redirect_uri - the redirect URI registered for this client. Required to build authorisation URLs via MoneyHub.Auth.
:token_endpoint_auth_method - :private_key_jwt (default) or :client_secret_basic.
:identity_url - override the OIDC issuer base URL.
:api_url - override the data API base URL.
:http_options - extra options merged into every Req request (for example [connect_options: [timeout: 5_000]]).
:finch_pool - the named Finch pool to use. Defaults to MoneyHub.Finch, started automatically by the MoneyHub.Application supervisor.