# API-only integration The following SCA methods can be handled using Token.io's API: - The **Redirect authentication** - the TPP redirects users to the bank interface for authentication. - Other authentication methods where additional credential information is required: - **Embedded authentication** - users authenticate using the TPP's interface. - **Decoupled authentication** - users carry out external authorization. See Bank selection for information on selecting banks, mandatory fields and authentication models. # Redirect authentication flow This section describes the API AIS integration where the TPP owns the full user experience. See the Token.io API reference for details of the following endpoints: - `GET /banks` - `POST /token-request` - `GET /token-requests/{tokenRequestId}/result` - `POST /token-requests/{tokenRequestId}/authorization` - `GET /accounts` - `GET /accounts/{accountId}` - `GET /account-balance` - `GET /accounts/{accountId}/balance` - `GET /accounts/{accountId}/standing-orders` - `GET /accounts/{accountId}/standing-orders/{standingOrderId}` - `GET /accounts/{accountId}/transactions` - `GET /accounts/{accountId}/transaction/{transactionId}` - `GET /tokens/{tokenId}` Use our Launchpad to test them. The image below is a simplified swim lane diagram of the integration flow. Details of the steps within the integration flow are shown below. ### 1. TPP retrieves list of banks TPPs retrieve the list of available banks using the `GET /banks` call. We recommend that this step is performed once daily, outside any AIS request, *e.g.*, at 11pm UTC, and that the result is cached. In the `GET /banks` request, there are numerous filtering criteria you can add as parameters to narrow your query. As a minimum, you should filter by your member ID. See Mandatory fields for information on which fields must be provided for a given bank to accept an AIS request. a. **TPP -> Token.io** - The TPP requests the list of banks from Token.io. b. **Token.io -> TPP** - Token.io supplies the list of banks to the TPP. ### 2. User selects bank The user selects the bank. a. **TPP -> User** - The TPP displays the bank selection screen. b. **User -> TPP** - The user selects the bank. ### 3. TPP collects consent from user The TPP collects consent from the user. For more information, see User consent collection. a. **TPP -> User** - The TPP initiates consent acceptance from the user. b. **User -> TPP** - The user gives consent to the TPP. ### 4. TPP initiates AIS request The TPP initiates the token request with Token.io using the `POST /token-requests` call. Token.io responds by acknowledging the details of the request. a. **TPP -> Token.io** - The TPP creates the token request using the `POST /token-requests` call. b. **Token.io -> TPP** - Token.io generates a response to the token request. ### 5. TPP requests authorization URL The TPP requests authorization using the `POST /token-requests/{tokenRequestId}/authorization` call. Token.io responds with the authorization URL. a. **TPP -> Token.io** - The TPP requests the bank authorization URL using the `POST /token-requests/{tokenRequestId}/authorization` call. b. **Token.io -> TPP** - Token.io returns the `redirectUrl` provided by the bank. ### 6. User completes authorization with bank The user completes authorization with the bank. a. **Bank -> User** - The bank displays the authorization page to the user. b. **User -> Bank** - The user authorizes the AIS request with the bank. ### 7. User redirect and callback The user is redirected and the TPP consumes the Token.io callback response. a. **Bank -> Token.io** - The bank redirects the user to Token.io. b. **Token.io -> TPP** - Token.io immediately redirects the user to the redirect URL provided by the TPP in the redirect URL parameter of the token-request call. The TPP then consumes the callback from Token.io. In the API-only integration with redirect authentication and TPP callback, only the `request-id` is returned in the callback response. Refer to Callback response for API-only integration for more details. ### 8. TPP obtains access token The TPP calls `GET /token-requests/{tokenRequestId}/result` to obtain the access token. a. **TPP -> Token.io** - The TPP calls Token.io using `GET /token-requests/{tokenRequestId}/result` to obtain the access token. b. **Token.io -> TPP** - Token.io responds with details of the access token. ### 9. TPP obtains account IDs The TPP calls `GET /tokens/{tokenId}` using the access token ID obtained in the previous step. The response contains the account IDs used for calls to the endpoints in the next step. a. **TPP -> Token.io** - The TPP calls Token.io using `GET /tokens/{tokenId}` to obtain the account IDs to use to retrieve the AIS data. b. **Token.io -> TPP** - Token.io responds with details of the account IDs. ### 10. TPP receives AIS data Depending on your use case, you can use one or more of the `Accounts` endpoints to retrieve relevant account information. See HTTP errors for information on HTTP error status codes. ## Embedded authentication flow In most cases, banks will redirect users to their website or mobile app. However, there are some scenarios where the bank requires the TPP to capture the fields needed for user authentication. This experience is referred to as embedded authentication. See the Token.io API reference for details of the following endpoints: - `GET /banks` - `POST /token-request` - `GET /token-requests/{tokenRequestId}/result` - `POST /token-requests/{tokenRequestId}/authorization` - `GET /accounts` - `GET /accounts/{accountId}` - `GET /account-balance` - `GET /accounts/{accountId}/balance` - `GET /accounts/{accountId}/standing-orders` - `GET /accounts/{accountId}/standing-orders/{standingOrderId}` - `GET /accounts/{accountId}/transactions` - `GET /accounts/{accountId}/transaction/{transactionId}` - `GET /tokens/{tokenId}` Use our Launchpad to test them. The image below is a simplified swim lane diagram of the integration flow. Details of the steps within the integration flow are shown below. ### 1. TPP retrieves list of banks The TPP retrieves the list of available banks using the `GET /banks` call. We recommend that this step is performed once daily, outside any AIS request, *e.g.*, at 11pm UTC, and that the result is cached. In the `GET /banks` request, there are numerous filtering criteria you can add as parameters to narrow your query. As a minimum, you should filter by your member ID. See Mandatory fields for information on which fields must be provided for a given bank to accept an AIS request. a. **TPP -> Token.io** - The TPP requests the list of banks from Token.io. b. **Token.io -> TPP** - Token.io supplies the list of banks to the TPP. ### 2. User selects bank The user selects the bank. a. **TPP -> User** - The TPP displays the bank selection screen. b. **User -> TPP** - The user selects the bank. ### 3. TPP collects consent from user The TPP collects consent from the user. For more information see User consent collection. a. **TPP -> User** - The TPP initiates consent acceptance from the user. b. **User -> TPP** - The user gives consent to the TPP. ### 4. TPP initiates AIS request The TPP initiates the token request with Token.io using the `POST /token-requests` call. Token.io responds by acknowledging the details of the request. a. **TPP -> Token.io** - The TPP creates the token request using the `POST /token-requests` call. b. **Token.io -> TPP** - Token.io generates a response to the token request. ### 5. TPP requests authorization with bank The TPP requests authorization using the `POST /token-requests/{tokenRequestId}/authorization` call. Token.io responds with the fields object, containing the initial fields required for the embedded flow. a. **TPP -> Token.io** - The TPP requests the authorization URL using the `POST /token-requests/{tokenRequestId}/authorization` call. Initial credentialFields from the response to `GET /banks` may be sent in the `credentials` field. The `useCredentialFlow` flag must be set to `true`. When this flag is set to `true`, the credential flow is triggered. The credentials map must be populated if required by the bank (see `credentialFields` in the response to `GET /banks`), otherwise empty credentials are used. The `useCredentialFlow` field should not be confused with `useWebAppCredentialsFlow`. When `useWebAppCredentialsFlow` is set to `true` and the bank's flow includes embedded steps, these steps are handled by Token.io's HP, rather than by the customer's own pages. See the `POST /token-requests/{tokenRequestId}/authorization` request for more details. b. **Token.io -> TPP** - Token.io returns the fields to be used in the embedded flow. The response can contain information relating to additional fields to be captured in the fields object. ### 6. TPP captures additional user credentials The TPP captures additional credentials from the user. a. **TPP -> User** - The TPP requests additional credentials from the user. b. **User -> TPP** - The user provides additional credentials to the TPP. ### 7. TPP submits additional user credentials to bank Using the `POST /token-requests/{tokenRequestId}/authorization` call, the TPP submits the additional credentials to the bank via Token.io. a. **TPP -> Token.io** - The TPP sends additional credentials using the `POST /token-requests/{tokenRequestId}/authorization` call. b. **Token.io -> TPP** - Token.io acknowledges receipt of the additional credentials and requests more, if required. c. **Token.io -> Bank** - Token.io sends this additional information to the bank. d. **Bank -> Token.io** - The bank confirms receipt of the information from Token.io. ### 8. User completes authorization with bank The user completes authorization with the bank. This is an optional step. For some banks, the user may not be redirected to the bank page for completing authorization. a. **Bank -> User** - The bank displays the authorization page to the user. b. **User -> Bank** - The user authorizes the AIS request with the bank. ### 9. TPP obtains access token The TPP calls `GET /token-requests/{tokenRequestId}/result` to obtain the access token. a. **TPP -> Token.io** - The TPP calls Token.io using `GET /token-requests/{tokenRequestId}/result` to obtain the access token. b. **Token.io -> TPP** - Token.io responds with details of the access token. ### 10. TPP obtains account IDs The TPP calls `GET /tokens/{tokenId}` using the access token ID obtained in the previous step. The response contains the account IDs used for calls to the endpoints in the next step. a. **TPP -> Token.io** - The TPP calls Token.io using `GET /tokens/{tokenId}` to obtain the account IDs to use to retrieve the AIS data. b. **Token.io -> TPP** - Token.io responds with details of the account IDs. ### 11. TPP receives AIS data Depending on your use case, you can use one or more of the `Accounts` endpoints to retrieve relevant account information. See HTTP errors for information on HTTP error status codes. ## Decoupled authentication flow With decoupled authentication, the bank carries out an additional form of authentication external to the API AIS integration. This model allows for a number of solutions, for example using a mobile phone to authenticate, or using biometrics for authentication through a separate terminal, such as a point of sale (POS) device. See the Token.io API reference for details of the following endpoints: - `GET /banks` - `POST /token-request` - `GET /token-requests/{tokenRequestId}/result` - `POST /token-requests/{tokenRequestId}/authorization` - `GET /accounts` - `GET /accounts/{accountId}` - `GET /account-balance` - `GET /accounts/{accountId}/balance` - `GET /accounts/{accountId}/standing-orders` - `GET /accounts/{accountId}/standing-orders/{standingOrderId}` - `GET /accounts/{accountId}/transactions` - `GET /accounts/{accountId}/transaction/{transactionId}` - `GET /tokens/{tokenId}` The image below is a simplified swim lane diagram of the integration flow. Details of the steps within the integration flow are shown below. ### 1. TPP retrieves list of banks The TPP retrieves the list of available banks using the `GET /banks` call. We recommend that this step is performed once daily, outside any AIS request, *e.g.*, at 11pm UTC, and that the result is cached. In the `GET /banks` request, there are numerous filtering criteria you can add as parameters to narrow your query. As a minimum, you should filter by your member ID. See Mandatory fields for information on which fields must be provided for a given bank to accept an AIS request. a. **TPP -> Token.io** - The TPP requests the list of banks from Token.io. b. **Token.io -> TPP** - Token.io supplies the list of banks to the TPP. ### 2. User selects bank The user selects the bank. a. **TPP -> User** - The TPP displays the bank selection screen. b. **User -> TPP** - The user selects the bank. ### 3. TPP collects consent from user The TPP collects consent from the user. For more information see User consent collection. a. **TPP -> User** - The TPP initiates consent acceptance from the user. b. **User -> TPP** - The user gives consent to the TPP. ### 4. TPP initiates AIS request The TPP initiates the token request with Token.io using the `POST /token-requests` call. Token.io responds by acknowledging the details of the request. a. **TPP -> Token.io** - The TPP creates the token request using the `POST /token-requests` call. b. **Token.io -> TPP** - Token.io generates a response to the token request. ### 5. TPP requests authorization with bank The TPP requests authorization using the `POST /token-requests/{tokenRequestId}/authorization` call. Token.io responds with the fields object, containing the initial fields. In the fields object the type is returned as DECOUPLED. a. **TPP -> Token.io** - The TPP requests the authorization URL using the `POST /token-requests/{tokenRequestId}/authorization` call. Initial credentialFields from the response to `GET /banks` may be sent in the credentials field. The `useCredentialFlow` flag must be set to `true`. When this flag is set to `true`, the credential flow is triggered. The credentials map must be populated if required by the bank (see `credentialFields` in the response to `GET /banks`), otherwise empty credentials are used. The `useCredentialFlow` field should not be confused with `useWebAppCredentialsFlow`. When `useWebAppCredentialsFlow` is set to `true` and the bank's flow includes embedded steps, these steps are handled by Token.io's HP, rather than by the customer's own pages. See the `POST /token-requests/{tokenRequestId}/authorization` request for more details. b. **Token.io -> TPP** - Token.io returns the fields object with type set to `DECOUPLED` and the message to be displayed to the user. See Decoupled callback response for more information on the TPP callback response. ### 6. TPP messages user and bank captures additional information The TPP is expected to show the message to the user and to wait for confirmation of receipt before proceeding to the next step. The bank will then challenge the user to authenticate themselves outside the API AIS request flow. This could be in the form of an SMS to the user’s registered phone number with the bank, or biometrics through a POS device. a. **TPP -> User** - The TPP displays the message to the user. b. **User -> TPP** - The user confirms receipt of the message. c. **Bank -> User** - The bank requests additional authentication from the user, through an external source, *e.g.*, SMS. POS. d. **User -> Bank** - The user provides additional authentication credentials to the bank via an external source. ### 7. TPP submits additional user credentials to bank Using the `POST /token-requests/{tokenRequestId}/authorization` call, the TPP submits the additional credentials to the bank via Token.io. a. **TPP -> Token.io** - The TPP sends additional credentials using the `POST /token-requests/{tokenRequestId}/authorization` call. b. **Token.io -> TPP** - Token.io acknowledges receipts of the additional credentials and requests more, if required. c. **Token.io -> Bank** - Token.io sends this additional information to the bank. d. **Bank -> Token.io** - The bank confirms receipt of the information from Token.io. ### 8. User completes authorization with bank The user completes authorization with the bank. a. **Bank -> User** - The bank displays the authorization page to the user. b. **User -> Bank** - The user authorizes the AIS request with the bank. ### 9. TPP obtains access token The TPP calls `GET /token-requests/{tokenRequestId}/result` to obtain the access token. a. **TPP -> Token.io** - The TPP calls Token.io using `GET /token-requests/{tokenRequestId}/result` to obtain the access token. b. **Token.io -> TPP** - Token.io responds with details of the access token. ### 10. TPP obtains account IDs The TPP calls `GET /tokens/{tokenId}` using the access token ID obtained in the previous step. The response contains the account IDs used for calls to the endpoints in the next step. a. **TPP -> Token.io** - The TPP calls Token.io using `GET /tokens/{tokenId}` to obtain the account IDs to use to retrieve the AIS data. b. **Token.io -> TPP** - Token.io responds with details of the account IDs. ### 11. TPP receives AIS data Depending on your use case, you can use one or more of the `Accounts` endpoints to retrieve relevant account information. See HTTP errors for information on HTTP error status codes. If you have any feedback about the developer documentation, please contact [devdocs@token.io](mailto:devdocs@token.io)