---
title: "Create an auth request"
method: POST
path: "/auth-requests"
tags: ["auth-requests"]
---

# Create an auth request

`POST /auth-requests`

Requires **auth_requests:write** scope.

## Request body

- AuthRequestPost
  - `redirectUri` string — One of the redirect uri that is set up under your API client. Required until separate bank registration is complete
  - `userId` string — The id of the user. Required for second use case - account access.
  - `scope` string, required — The scope for the auth request
  - `connectionId` string — The connection id. Required when scope has 'reauth' or 'refresh'
  - `payment` object
    - `amount` integer — Payment amount in minor units of the currency, eg. pennies for GBP.
    - `payee` object
      - `accountNumber` string — The account number of the payee
      - `sortCode` string — The sort code of the payee
      - `name` string — The name of the payee
    - `payer` object
      - `accountNumber` string — The account number of the payer
      - `sortCode` string — The sort code of the payer
      - `name` string — The name of the payer
    - `payeeId` string, uuid — Payee id
    - `payeeType` 'api-payee' | 'mh-user-account' — Type of payee
    - `payerId` string — Payer Id
    - `payerRef` string — Reference to display on payer's statement
    - `payerType` 'mh-user-account' | 'api-payer' — Payer Type
    - `payerName` string — Payer name
    - `payerEmail` string, email — Payer email
    - `readRefundAccount` boolean — Determines whether to read the refund account details
    - `context` 'Other' | 'PartyToParty' | 'BillPayment' — The context of the payment
    - `endToEndId` string — Unique identifier relevant to the transaction - Allowed characters (a-zA-Z0-9 :-).
  - `standingOrder` object
    - `payee` object
      - `accountNumber` string — The account number of the payee
      - `sortCode` string — The sort code of the payee
      - `name` string — The name of the payee
    - `payeeId` string, uuid — Payee id
    - `payeeType` 'api-payee' | 'mh-user-account' — Type of payee
    - `payerId` string — Payer Id
    - `payerType` 'mh-user-account' | 'api-payer' — Payer Type
    - `context` 'Other' | 'PartyToParty' | 'BillPayment' — The context of the payment
    - `reference` string — The name or description given to the standing order
    - `frequency` object
      - `repeat` 'Daily' | 'Weekly' | 'Monthly' | 'Quarterly' | 'Yearly', required
      - `day` number — The number of the day on which to repeat the payment
      - `week` number — The number of the week on which to repeat the payment
      - `month` number — The number of the month on which to repeat the payment
      - `onlyWorkDays` boolean — Specifies whether the payment should only be made on working days
      - `region` 'ENGLISH' | 'SCOTTISH' | 'RECEIVED' — The region for dates of quarterly payments
    - `numberOfPayments` integer — The number of reucrring payments to complete the standing order
    - `firstPaymentDate` string, date-time
    - `recurringPaymentDate` string, date-time
    - `finalPaymentDate` string, date-time
    - `firstPaymentAmount` integer — The value of the first payment in minor units of the currency, eg. pennies for GBP.
    - `recurringPaymentAmount` integer — The value of the next payment in minor units of the currency, eg. pennies for GBP.
    - `finalPaymentAmount` integer — The value of the final payment in minor units of the currency, eg. pennies for GBP.
    - `currency` string — The currency of the standing order
  - `recurringPayment` object
    - `payee` object
      - `accountNumber` string — The account number of the payee
      - `sortCode` string — The sort code of the payee
      - `name` string — The name of the payee
    - `payeeId` string, uuid — Payee id
    - `payeeType` 'api-payee' | 'mh-user-account' — Type of payee
    - `payerId` string — Payer Id
    - `payerType` 'mh-user-account' | 'api-payer' — Payer Type
    - `context` 'Other' | 'PartyToParty' | 'BillPayment' — The context of the payment
    - `reference` string — The name or description given to the recurring payment
    - `validFromDate` string, date-time — The date from which the authorisation is effective
    - `validToDate` string, date-time — The date to which the authorisation is effective
    - `maximumIndividualAmount` integer — The maximum single payment amount in minor units of the currency, eg. pennies for GBP.
    - `currency` string — The currency of the maximum payment amount
    - `periodicLimits` object[]
      - `amount` number — The maximum amount for this recurring payment limit
      - `currency` string — The currency code for this recurring payment limit
      - `periodType` 'Day' | 'Week' | 'Fortnight' | 'Month' | 'Half-year' | 'Year' — The currency code for this recurring payment limit
      - `periodAlignment` 'Consent' | 'Calendar' — The currency code for this recurring payment limit
    - `type` string[] — Specifies the type of payments to be made
  - `reversePayment` object
    - `paymentId` string, uuid — The id of the payment to reverse
    - `amount` integer — Payment amount in minor units of the currency, eg. pennies for GBP. It must be less than the payment that is being reversed. If not specified, it will default to the full amount of the original payment.
    - `payerId` string — Payer Id
    - `payerType` 'mh-user-account' | 'api-payer' — Payer Type
  - `categorisationType` 'personal' | 'business' — Type of transaction categorisation to use. Defaults to personal categories
  - `benefitsCheck` boolean — If you require the connection to check for benefits payments, set this to true
  - `counterpartiesCheck` string[] — If set, will check the connection for transactions with these counterparties. Will return true if one exists.
  - `permissions` string[] — Defines permissions, which can enable functionalities like standing orders or beneficiaries. Can also be used to apply a lighter set of permissions than the default set. The behavior depends on 'permissionsAction'.
  - `permissionsAction` 'add' | 'replace' — Dictates how 'permissions' function. 'add' (default) to increment, or 'replace' to substitute default permissions.
  - `expirationDateTime` string, date-time — The date time that an AIS consent will expire at. If no user ID is provided, expiry will default to 24 hours. Maximum allowed 90 days from now.
  - `transactionFromDateTime` string, date-time — The date time transactions will be retrieved from. Maximum allowed depends on the connection. Use /well-known/openid-configuration to get the maximum allowed time period for the connection.
  - `sync` object — Options for the sync of a connection
    - `enableAsync` boolean — If set to true, the sync for data will happen in the background
    - `failOnTimeout` boolean — If set to true, a sync timeout will fail the auth flow instead of returning a partial result with syncId
  - `customerIpAddress` string, ipv4 — This field could be used to pass the custom customer's IP address to the bank.
  - `accountVerification` object — Enables simple account verification AIS consent request
    - `accVerification` boolean — If set to true, the generic permissions will be replaced by the ReadAccountsDetail permission
  - `customerLastLoggedTime` string — The time when the customer last logged in represented as an ISO 8601 date-time format including timezone
  - `accountTypes` string[] — Filter which accounts to store based on their type
  - `accountIdentification` string[] — Filter which accounts to store by providing either sort code and account number (concatenated), IBAN or PAN

## Response `200`

Successful Auth Request Response

- object
  - `data` AuthRequestPostResponse
    - `id` string, uuid, required — The id of the auth request
    - `redirectUri` string — The redirect uri sent when creating the auth request
    - `createdAt` string, date-time, required — The date that the auth request was created.
    - `bankId` string, required — The id of the bank
    - `userId` string — The id of the user
    - `scope` string, required — The scope sent when creating the auth request
    - `paymentId` string, uuid — Id of the payment when the auth request had the payment scope
    - `status` 'complete' | 'pending' | 'error' | 'deleted', required — The status of the auth request
    - `redirectParams` object, required
      - `authUrl` string — The url at the financial institution to redirect the user towards
      - `returnUrl` string — The url that the user will be returned to afer they have authorized
      - `state` string — The `state` params that will be included in the query params or hash fragment when the user is redirected back
  - `meta` object

## Other responses

- `400` — Unsuccessful Response - Bad request - Missing query parameters - Missing body properties
- `401` — Unsuccessful Response - Not authorised - Missing authorization header - Invalid access Token
- `403` — Unsuccessful Response - Forbidden - Invalid scopes

---

[API](https://skmtc.net/moneyhubenterprise/apis/moneyhub-identity-service.md) · [All operations](https://skmtc.net/moneyhubenterprise/apis/moneyhub-identity-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/moneyhubenterprise/moneyhub-identity-service/revisions/8841721f7aae/schema)