Exchange One-time-token to retrieve user consent

Yapily Authorisation API now supports optional layers of added security 🛡️when it comes to exchanging of user consents via the browser (user-agent).

In scenarios where the browser (user-agent) could be compromised, the TPP can use the Yapily’s one-time-token as a means of additional security. By doing that, the final consent token is not exposed on the browser and must be only retrieved server side.

How? 🤔

Execute the existing auth-request with a property called one-time-token. Receive the one-time-token in the callback on the client user-agent, and use it to retrieve the consent-token.

You can use the one-time-token on both authorisation requests for:

• Account Information
• Payment Initiation

The same flow works for payments as well, thus the payment token can already be used only once, it might be required to not expose it in some sensitive use cases.

Let’s see how this works for account authorisation requests.

1. Enable one-time-token in auth request

• Set "oneTimeToken":"true" in the auth request object.

POST https://api.yapily.com/account-auth-requests
Request Body:
{
 "userUuid": "{{user-uuid}}",
 "institutionId": "{{institution-id}}",
 "callback": "https://yourdomain.com",
 "oneTimeToken": "true",
 "accountRequest": {
  "transactionFrom": "{{transactions-from}}",
  "transactionTo": "{{transactions-to}}",
  "expiresAt": "{{expires-at}}"
 }
}

Note: "oneTimeToken" is optional. If not present the callback will return the consent-token by default.

• Load the user-agent with the authorisationUrl to display the user with the consent request page of the bank.
• If the user authorised successfully then the user-agent is redirected to the callback URL containing the one-time-token as a query parameter.

https://yourdomain.com/?one-time-token={{one-time-token}}

2. Exchange the one-time-token with the consent token

Retrieve the consent-token by supplying the one-time-token.

POST https://api.yapily.com/consent-one-time-token
Request Body:
{
  "oneTimeToken":"{{one-time-token}}"
} 

Status of one-time-token will now be set to “claimed” and one-time token usage is complete.

Observations:

• One time token cannot be used again after successful retrieval of consent.
• One time token cannot be used without a valid callback configured.
• One time token has a 3 min expiry set and it will be valid if accessed during that time frame. Alternatively, please retrieve the consent using the unique {{consentId}} if OTT fails/ expires.

API Reference: https://docs.yapily.com/#82712468-cd42-48aa-84e6-fbe1ee770c77

Release Note: https://medium.com/yapilychangelog/2019-03-08-71874f37c3ad