Auth Requests

The Auth Requests interaction flow is aimed for any of the following scenarios:

• Organisations who have their own AIS / PIS permissions and use Moneyhub as a Technical Service Provider (TSP).
• Organisations that require authorisations to work consistently with private browsing sessions.
• Organisations that have a mobile app and would like to improve their app to app flow.

Organisations that would still like to use Moneyhub consent screen will need to generate Authorisation requests as described in our Authentication section.

We provide RESTful endpoints for "auth requests".
The flow can briefly be described as follows:

1. User wants to connect to Bank X
2. Client POSTs to the /auth-requests endpoint with the bank id and user id
3. Moneyhub creates an "auth request" and returns an id an authUrl (which is at Bank X) and a state param
4. Client needs to show their own consent page approved by Moneyhub and then redirect the user to the authUrl .
5. User authenticates at the bank and is redirected to either:

• Client's registered redirect uri: this is the case when the client has their own certificates and is registered directly with the bank and we act as a Technical Service Provider
• Moneyhub's redirect uri: this is the case when we the certificates that are being used are ours.

6. (If the user is redirected to Moneyhub's redirect uri, we will immediately redirect to the Client's registered redirect uri)
7. Client parses the query params or hash fragment that contains the state, code and id_token that are present on the redirect_uri and sends a PATCH request to the /auth-requests/:id endpoint with the parsed auth params. (Client can match sessions by comparing the state returned when creating an auth request, and the state that is sent to the redirect_uri.
8. Moneyhub processes the auth params, uses them to gain an access token for the user from Bank X and creates a connection. A connection id (and optionally payment id) is returned in the response of the PATCH request.
9. The Client can now access the data APIs to retrieve data about the user's accounts or the payment that has been initiated.

As of version 3.9.0 the Moneyhub API Client supports auth requests.
Please see the examples folder for usage examples: https://github.com/moneyhub/moneyhub-api-client/tree/master/examples/auth-requests

Swagger documentation is available here
API reference to the endpoints can be found here

POST /auth-requests

This endpoint is used to create an auth request. It needs an access token with the scope: auth_requests:write It expects the following data payload:

{
	 scope: "openid payment id:123", // required
   redirectUri: "your redirect uri", // required until separate bank registration is complete 
   payment: {
        payeeId: "the payee id", // payeeId or payee required for payments
        payee: { // payeeId or payee required for payments
          accountNumber: "12345678",
          sortCode: "123456",
          name: "payee name"
        },
        amount: 100, // required for payments
        payerRef: "payer ref", // required for payments
   }, // required for payments
   userId, // required for "Ongoing account access"
   connectionId, // required for "reauth" 
   categorisationType // optional
}

The response contains:

{
	id: "the id of the auth request",
  redirectUri: "your redirect uri",
  createdAt: "when the request was created",
  bankId: "the bank id",
  userId: "the user id", // this will be created on POST
  scope: "the scope, e.g. openid payment id:123",
  connectionId: null, // this will normally be null until after a succesful PATCH
  status: "pending", // error|deleted|complete|pending
  redirectParams: {
    authUrl: "the url at the bank to redirect the user to",
    returnUrl: "the url that the bank will redirect the user to",
    state: "the state param that the bank will include when they redirect the user"
  }
}

PATCH /auth-requests/:id

This endpoint is used to update an auth request. It needs an access token with the scope: auth_requests:write It expects the following data payload:

{
  authParams: {
    "code": "code",
    "state": "state",
    "id_token": "id_token",
    "error": "error",
    "error_description": "error description"
  }
}
// These are the params that the bank will send to your redirect uri

The code from the bank can only be used once, and can last up to 10 minutes, but often less than that. It's recommended to use the code as quickly as possible - ideally within 10 seconds, and certainly within 60 seconds.

The response contains:

{
	id: "the id of the auth request",
  redirectUri: "your redirect uri",
  createdAt: "when the request was created",
  bankId: "the bank id",
  userId: "the user id",
  scope: "the scope, e.g. openid payment id:123",
  connectionId: "the connection id",
  paymentId: "the payment id",
  status: "complete", // error|deleted|complete|pending
}

GET /auth-requests/:id

This is a simple GET route that returns the current state of the auth-request. It needs an access token with the scope: auth_requests:read

GET /auth-requests

This is a simple GET route that returns a paginated list of all the auth-requests for your client. It needs an access token with the scope: auth_requests:read

It accepts the following query parameters