MoneyHub.Claims (MoneyHub v1.0.0)

Copy Markdown View Source

Builds the OIDC claims request parameter Moneyhub uses to drive connection behaviour.

Moneyhub layers a set of mh:* custom claims on top of standard OIDC claims. They're passed as the (URL-encoded, JSON-serialised) claims parameter on the authorisation request - either inline, wrapped in a signed request object (see MoneyHub.Auth.PrivateKeyJWT), or via Pushed Authorisation Requests (see MoneyHub.Auth).

Every claim lives under id_token in the resulting JSON (Moneyhub does not currently read claims from userinfo).

Example: register a new user for ongoing access

MoneyHub.Claims.new()
|> MoneyHub.Claims.put_sub()
|> MoneyHub.Claims.to_json()

Example: connect a specific existing user

MoneyHub.Claims.new()
|> MoneyHub.Claims.put_sub("5c1907c0e6b340e5c056fb2a")
|> MoneyHub.Claims.to_json()

Example: refresh an existing connection

MoneyHub.Claims.new()
|> MoneyHub.Claims.put_sub("5c1907c0e6b340e5c056fb2a")
|> MoneyHub.Claims.put_connection_id("b74f1a79f0be8bdb857d82d0f041d7d2:0f1aa7c1-6379-483a-bfd8-ae0a208fb635")
|> MoneyHub.Claims.to_json()

Example: create a single immediate payment

MoneyHub.Claims.new()
|> MoneyHub.Claims.put_sub()
|> MoneyHub.Claims.put_payment(%{
  "amount" => %{"amount" => 10.5, "currency" => "GBP"},
  "creditorAccount" => %{"identification" => %{"sortCode" => "010203", "accountNumber" => "12345678"}},
  "reference" => "Invoice 123"
})
|> MoneyHub.Claims.to_json()

Summary

Types

t()

Functions

new()

Starts an empty claims builder.

put(claims, claim_name, opts \\ [])

Sets an arbitrary mh:* (or any other) claim under id_token with the given essential flag and/or fixed value. Use this for claims not yet covered by a dedicated put_*/2 function.

put_category_type(claims, type)

Sets the mh:cat_type claim, controlling whether returned transactions are categorised using the "personal" or "business" category set.

put_connection_id(claims, connection_id)

Sets the mh:con_id claim to target a specific existing connection - used to refresh/re-sync a connection or to request re-authentication (re-consent) for it.

put_payment(claims, payment)

Sets the mh:payment claim with the given payment request payload, driving a single immediate payment authorisation.

put_recurring_payment(claims, recurring_payment)

Sets the mh:recurring_payment claim, driving a Variable Recurring Payment (VRP) consent authorisation.

put_standing_order(claims, standing_order)

Sets the mh:standing_order claim, driving a standing order creation authorisation.

put_sub(claims, user_id \\ nil)

Sets the sub claim, identifying which Moneyhub user this connection or action belongs to.

to_json(claims)

Serialises the claims builder to a JSON string suitable for the claims authorisation parameter.

to_json!(claims)

Same as to_json/1 but raises on failure.

Types

t()

@type t() :: %{optional(String.t()) => term()}

Functions

new()

@spec new() :: t()

Starts an empty claims builder.

put(claims, claim_name, opts \\ [])

@spec put(t(), String.t(), keyword()) :: t()

Sets an arbitrary mh:* (or any other) claim under id_token with the given essential flag and/or fixed value. Use this for claims not yet covered by a dedicated put_*/2 function.

put_category_type(claims, type)

@spec put_category_type(t(), :personal | :business) :: t()

Sets the mh:cat_type claim, controlling whether returned transactions are categorised using the "personal" or "business" category set.

put_connection_id(claims, connection_id)

@spec put_connection_id(t(), String.t()) :: t()

Sets the mh:con_id claim to target a specific existing connection - used to refresh/re-sync a connection or to request re-authentication (re-consent) for it.

put_payment(claims, payment)

@spec put_payment(t(), map()) :: t()

Sets the mh:payment claim with the given payment request payload, driving a single immediate payment authorisation.

payment is the raw payment request map (amount, creditor account, reference, and so on) as documented for the payments API.

put_recurring_payment(claims, recurring_payment)

@spec put_recurring_payment(t(), map()) :: t()

Sets the mh:recurring_payment claim, driving a Variable Recurring Payment (VRP) consent authorisation.

put_standing_order(claims, standing_order)

@spec put_standing_order(t(), map()) :: t()

Sets the mh:standing_order claim, driving a standing order creation authorisation.

put_sub(claims, user_id \\ nil)

@spec put_sub(t(), String.t() | nil) :: t()

Sets the sub claim, identifying which Moneyhub user this connection or action belongs to.

Called with no user_id, this marks the claim essential without a fixed value, letting Moneyhub assign a new user and report their id in the returned id_token (used when registering a brand-new user). Called with a user_id, it pins the connection/action to that specific, already-registered user.

to_json(claims)

@spec to_json(t()) :: {:ok, String.t()} | {:error, MoneyHub.Error.t()}

Serialises the claims builder to a JSON string suitable for the claims authorisation parameter.

to_json!(claims)

@spec to_json!(t()) :: String.t()

Same as to_json/1 but raises on failure.