Widgets V2 Auth URL Reference

Your backend requests a widget URL by calling the auth-url endpoint. This page is the request reference: it lists every option the request accepts and which options each widget type supports.

For an end-to-end walkthrough — creating a widget, creating a launch client, and loading the widget URL in an iframe — see Widgets V2 Getting Started.

📘

Keep credentials on your backend

Always call auth-url from your server. Never put your client secret, private key, or client assertions in frontend code.

Endpoint

POST https://widget-pages.moneyhub.co.uk/api/{widgetType}/auth-url
Content-Type: application/json

{widgetType} in the path must match the widget's Type in Admin Portal, and the widgetId in the body must be a widget of that type. If they do not match, the request fails. The supported widget types are listed under Widget types.

Authenticating the request

The launch client authenticates with one of two methods, set by tokenEndpointAuthMethod:

• client_secret_basic (the default) — used by Sandbox launch clients. Send the launch client's clientSecret.
• private_key_jwt — used by Live launch clients. Send a short-lived, single-use clientAssertion (a JWT signed with your private key) and the clientAssertionType.

See Widgets V2 Getting Started for how to create each launch client type, generate a key pair, and sign a client assertion.

Request body

The user must belong to the same API business as the widget and launch client. sub works for both sandbox and live widgets. To create a user and get their user id, see API Users.

The params object

params carries per-launch values through to the widget. Send {} if you have none. The fields below are recognised; any additional fields you include are passed through to the widget unchanged.

affordabilityApplicationSalary

The partner-declared gross annual income for the application. The widget passes it through to the affordability pre-submission checks.

{
  "affordabilityApplicationSalary": {
    "value": 3200000,
    "currency": "GBP"
  }
}

• value: a positive integer in minor units (pence for GBP). 3200000 is £32,000.
• currency: must be GBP.

For full behaviour and scope requirements, see Pre-submission checks application salary.

Widget types

Each widget type accepts the same request body, but differs in whether it needs a user and whether it runs the connections journey (shared bank-connection flow with an OAuth return URL).

• User required — the launch fails unless you send sub (or params.userId). For the other widgets, sub is optional: send it to show a specific user's data, or omit it to run with client-level access only.
• Connections journey — for connections-widget and affordability-widget, the service must resolve a redirect URI for bank OAuth (stored for the widget session). You do not have to send redirectUri on auth-url: when omitted, the service uses the Moneyhub-hosted widget page for that widget version (the same URL pre-filled under Redirect URIs). Send redirectUri (or params.redirectUri) only when you want users to return to your own site or app after connecting a bank; it must exactly match one of the widget's registered redirect URIs. Launch fails with Missing redirectUri for {widgetType} launch... only when the service cannot resolve a redirect URI (for example, the widget has no deployable version). Other widget types ignore redirectUri.

Examples

Sandbox widget (client secret)

A transaction-widget launched for a specific user:

curl -X POST "https://widget-pages.moneyhub.co.uk/api/transaction-widget/auth-url" \
  -H "Content-Type: application/json" \
  -d '{
    "widgetId": "YOUR-WIDGET-ID",
    "clientId": "YOUR-LAUNCH-CLIENT-ID",
    "clientSecret": "YOUR-LAUNCH-CLIENT-SECRET",
    "sub": "MONEYHUB-USER-ID",
    "params": {}
  }'

Live connections widget (private key JWT)

A connections-widget, which always needs a user. Omit redirectUri to keep users on the Moneyhub-hosted page after bank connection, or set it to your own callback URL (see Choosing a redirect URI):

curl -X POST "https://widget-pages.moneyhub.co.uk/api/connections-widget/auth-url" \
  -H "Content-Type: application/json" \
  -d '{
    "widgetId": "YOUR-WIDGET-ID",
    "clientId": "YOUR-LAUNCH-CLIENT-ID",
    "tokenEndpointAuthMethod": "private_key_jwt",
    "clientAssertion": "YOUR-CLIENT-ASSERTION",
    "clientAssertionType": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "sub": "MONEYHUB-USER-ID",
    "params": {}
  }'

Affordability widget with application salary

An affordability-widget that passes the application salary through to the pre-submission checks:

curl -X POST "https://widget-pages.moneyhub.co.uk/api/affordability-widget/auth-url" \
  -H "Content-Type: application/json" \
  -d '{
    "widgetId": "YOUR-WIDGET-ID",
    "clientId": "YOUR-LAUNCH-CLIENT-ID",
    "clientSecret": "YOUR-LAUNCH-CLIENT-SECRET",
    "sub": "MONEYHUB-USER-ID",
    "redirectUri": "https://your-site.example/callback",
    "params": {
      "affordabilityApplicationSalary": {
        "value": 3200000,
        "currency": "GBP"
      }
    }
  }'

Response

A successful request returns the widget URL:

{
  "data": {
    "widgetUrl": "https://..."
  }
}

Pass widgetUrl to your frontend and set it as the src of an iframe. The URL contains a short-lived token, so load it straight away and request a new one for each user session. See Use the widget URL.

Errors

A failed request returns 400 Bad Request with a message describing the problem.

The request body is also validated: a missing required field, an unknown field, or the wrong authentication fields for the chosen tokenEndpointAuthMethod return 400 Bad Request.