---
title: "Start authorization flow"
method: POST
path: "/v3/mandates/{id}/authorization-flow"
tags: ["Mandates"]
---

# Start authorization flow

`POST /v3/mandates/{id}/authorization-flow`

## Request

- Base URL: `https://api.truelayer-sandbox.com`
- URL: `https://api.truelayer-sandbox.com/v3/mandates/{id}/authorization-flow`
- Auth: one of:
  - OAuth 2
    - Client credentials
    - Token URL: `https://auth.truelayer.com/connect/token` scopes: `mandates`
  - HTTP bearer

Start the authorization flow for a mandate.

This API can be called:
- using the `mandate_token` associated with the Mandate you are trying to fetch; or
- using a backend bearer token.

## Path parameters

- `id` string, required: Unique ID for the mandate

## Headers

- `Idempotency-Key` string
- `Tl-Signature` string

## Request body

- StartMandateAuthorizationFlow
  - `provider_selection` object, required: Can the UI render a provider selection screen?
  - `redirect` object, required: Can the UI redirect the end user to a third-party page? Configuration options are available to constrain if TrueLayer's Hosted Payment Page should be leveraged.
    - `return_uri` string, url, required: During the authorization flow the end user might be redirected to another page (e.g. bank website, TrueLayer's Hosted Payment Page). This URL determines where they will be redirected back once they completed the flow on the third-party's website. `return_uri` must be one of the allowed `return_uri`s registered in TrueLayer's Console.
  - `consent` object: Can the UI capture the user's consent? This field declares whether the UI supports the `consent` action, which is used to explicitly capture the end user's consent for initiating the payment. If it is omitted, the flow will continue without a `consent` action.

## Response `200`

Mandate Authorization Flow

- union
  - MandateAuthorizationFlowAuthorizing
    - `status` 'authorizing', required
    - `authorization_flow` MandateAuthorizationFlow, required: Contains information regarding the nature and the state of the authorization flow
      - `actions` object, required
        - `next` union, required: The next action can be performed via `POST /v3/mandate/{id}/authorization_flow/action/{action_name}` - check its documentation for relevant examples.
          - ActionSpecProviderSelection: Provider selection represents the end user action of selecting a provider
            - `type` 'provider_selection', required
            - `providers` Provider[], required: List of providers to be presented to the end user
              - …
          - ActionSpecRedirect
            - `type` 'redirect', required
            - `uri` string, url, required: URL the end user must be redirected to.
          - ActionSpecWaitForOutcome2: Indication that there are currently no actions to perform.
            - `type` 'wait', required
            - `display_message` DisplayText
              - …
            - `async_outcome` object: It indicates that the user flow can continue and you can check the mandate status later. You don't need to wait synchronously for the status to change at this point.
          - ActionSpecConsent2
            - `type` 'consent', required
            - `subsequent_action_hint` 'redirect', required
  - MandateAuthorizationFlowAuthorizationFailed
    - `status` 'failed', required
    - `failure_stage` 'authorization_required' | 'authorizing' | 'authorized', required: The status the mandate was in when it failed.
    - `failure_reason` string, required: A readable detail for why the mandate failed. Example values to expect: - `authorization_failed` - `provider_error` - `provider_rejected` - `internal_server_error` - `invalid_sort_code` - `invalid_request` - `expired` - `unknown_error`

## Other responses

- `400`: Invalid Request
- `401`: Unauthenticated
- `403`: Forbidden
- `404`: Mandate Not Found
- `409`: Conflict
- `422`: Idempotency-Key Reuse
- `500`: Unknown Error

---

[API](https://skmtc.dev/truelayer/apis/payments-api-v3.md) - [All operations](https://skmtc.dev/truelayer/apis/payments-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/truelayer/apis/payments-api-v3/revisions/a7c585fc9b84?raw)