---
title: "Initiate bank authorization"
method: POST
path: "/token-requests/{tokenRequestId}/authorization"
tags: ["Requests - for Payments v1 or AIS"]
---

# Initiate bank authorization

`POST /token-requests/{tokenRequestId}/authorization`

The `POST /token-requests/{tokenRequestId}/authorization` endpoint initiates the bank authorization process with a given bank id and token request id.

## Path parameters

- `tokenRequestId` string, required

## Request body

- InitiateBankAuthorizationRequest — Contains the consent information for the original request.
  - `consentAccepted` boolean — This flag indicates whether the user has grated consent for the payment in the TPP's user interface.
  - `credentials` InitiateBankAuthorizationRequestCredentialsEntry — Maps a bank-defined credential id string to a value.
  - `useCredentialFlow` boolean — If true, this triggers the credential flow. The credentials map must be populated if required by the bank (see `credentialFields` in the response to `GET /banks`). Otherwise, empty credentials are used.
  - `useWebappCredentialsFlow` boolean — When useWebAppCredentialsFlow is set to true and bank's flow includes embedded steps, these steps are handled by Token.io's Hosted Pages, rather than by the customer's own pages.

## Response `200`

Successful response

- union
  - object
    - `fields` CredentialFields
      - `fields` CredentialField[] — Contains information used in embedded authentication flows. These are optional credential request fields. When provided, the TPP should call `initiateBankAuth` again to provide the credentials.
        - `description` string — The description of the credentials.
        - `displayName` string — The display name for the credentials.
        - `flickerCode` string — The Flicker code displayed to the user.
        - `id` string — Specifies the identifier to be used when passing the value for this credential.
        - `image` string — A Base64 representation of an image displayed to the user.
        - `options` string[] — A list of options for the user to select from. For example, it can be an SCA method choice (SMS message, phone call <i>etc</i>.), or confirm/decline options for a confirmation page. The customer sends one of the values back to Token.io with the corresponding id.
        - `type` 'INVALID' | 'FIELD' | 'PASSWORD' | 'PSU_MESSAGE' | 'IMAGE' | 'FLICKER' | 'DECOUPLED' — Specifies the type of credential.
    - `oauthState` string — The authorization state parameter generated within Token.io in the response. It is an optional field.
  - object
    - `redirectUrl` string — This URL redirects the user after bank authentication.
    - `oauthState` string — The authorization state parameter generated within Token.io in the response. It is an optional field.
  - object
    - `status` 'INVALID' | 'AUTHENTICATED' | 'AUTHENTICATION_FAILED' | 'DECLINED_BY_PSU' — This status indicates whether the SCA process succeeded or failed.
    - `oauthState` string — The authorization state parameter generated within Token.io in the response. It is an optional field.

## Other responses

- `400` — The client specified an invalid argument
- `401` — The authorization information is missing or invalid
- `403` — Permission to access this endpoint is denied
- `404` — The requested entity, such as a payment, was not found
- `429` — Too many requests
- `500` — An unexpected or internal server error
- `501` — The operation was not implemented
- `503` — Service is unavailable
- `504` — Gateway has timed out

---

[API](https://skmtc.net/token/apis/token-io-s-open-banking-api-for-tpps.md) · [All operations](https://skmtc.net/token/apis/token-io-s-open-banking-api-for-tpps/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/token/token-io-s-open-banking-api-for-tpps/versions/5e8d6d2c24a1/schema)