# Authorisations This guide shows how to perform PSU authorisation when interacting with our APIs. It covers the different authorisation flows supported by the API and provides a step-by-step overview of how to complete them successfully. Our API supports two main authorisation flows: * Redirect - where the PSU is redirected to their bank to complete the authorisation. * Decoupled - where the PSU completes the authorisation embedded in your own interface. The overall authorisation process is the same regardless of the type of resource being authorised — whether it's a consent, a single payment, or a signing basket. This guide therefore uses variables instead of resource-specific fields. #### Resource Variables | Variable | Consents | Payments | Signing Baskets | | ------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | `resourceBasePath` | psd2/consent/v1/consents/{consentId} | psd2/paymentinitiation/v1/{payment-service}/{payment-product}/{paymentId} | psd2/paymentinitiation/v1/signing-baskets/{basketId} | | `resource` | consent | payment | basket | | `ResourceType` | Consent | Payment | Basket | | `resourceScope` | accountinformation corporate/private | paymentinitiation corporate/private | paymentinitiation corporate/private | In this guide, the flows for decoupled and redirect authorisation are outlined separately to highlight any flow-specific steps. ## Decoupled Flow ### 1. Create Authorisation The first step after creating a resource is to create an authorisation process for that resource. The response will provide a list of available SCA methods for the specified bank. #### Endpoint ```http POST /{resourceBasePath}/authorisations ``` #### Request Headers | Name | Type | Description | | ------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------- | | `X-Request-ID` | string(uuid) | The ID of the request, unique to the call, as determined by the initiating party. | | `X-BicFi` | string | The BIC of the bank to which the request is addressed. | | `PSU-ID` | string | The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID. | | `PSU-Corporate-ID` | string | The Corporate ID of the PSU when acting on behalf of an organisation, e.g. Org. nummer for SE, KVK for NL. | | `TPP-Redirect-Preferred` | boolean | Indicates a preference for redirect-based SCA over decoupled when set to `true`. The bank may not support both types. | | `PSU-IP-Address` | string(ipv4) | The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU. | | `PSU-User-Agent` | string | The forwarded Agent header field of the HTTP request between PSU and TPP, if available. | ```bash curl -X POST "https://api.openbankingplatform.com/{resourceBasePath}/authorisations" \ -H "Authorization: Bearer " \ -H "X-Request-ID: 6c2fd2da-d90e-4cc9-944b-0e470594540d" \ -H "X-BicFi: ESSESESS" \ -H "PSU-ID: 199002092386" \ -H "PSU-Corporate-ID: 5560160680" \ -H "TPP-Redirect-Preferred: false" \ -H "PSU-IP-Address: 152.120.171.187" \ -H "PSU-User-Agent: mozilla/5.0" ``` #### Response ```json { "authorisationId": "10f647b2-2ec3-48a5-845b-c3851cde1acb", "scaMethods": [ { "authenticationType": "PUSH_OTP", "authenticationMethodId": "mbid", "name": "Mobilt BankID" }, { "authenticationType": "CHIP_OTP", "authenticationMethodId": "mbid_same_device", "name": "Mobile BankID on this device" }, { "authenticationType": "PHOTO_OTP", "authenticationMethodId": "mbid_animated_qr_token", "name": "Mobile BankID on another device" } ], "scaStatus": "received" } ``` ### 2. Start Authorisation This request triggers the authentication flow. Here, you select the appropriate SCA method for the PSU's context and initiate the authentication process. This is done by taking the `authenticationMethodId` of an SCA method listed in the previous step and including it in the request body. If the bank supports animated QR, the response from the previous step will include an element with `mbid_animated_qr_image` or `mbid_animated_qr_token` as the `authenticationMethodId`, which should be used if the authentication is to be performed on another device. If the authentication is to be performed on the same device, `mbid_same_device` (or `mbid` if not available) should be used. #### Endpoint ```http PUT /{resourceBasePath}/authorisations/{authorisationId} ``` #### Path Parameters | Name | Type | Description | | ----------------- | ------ | ------------------------------------------------------| | `authorisationId` | string | The ID of the authorisation process that was created. | #### Request Headers | Name | Type | Description | | ------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------- | | `X-Request-ID` | string(uuid) | The ID of the request, unique to the call, as determined by the initiating party. | | `X-BicFi` | string | The BIC of the bank to which the request is addressed. | | `PSU-ID` | string | The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID. | | `PSU-Corporate-ID` | string | The Corporate ID of the PSU when acting on behalf of an organisation, e.g. Org. nummer for SE, KVK for NL. | | `TPP-Redirect-Preferred` | boolean | Indicates a preference for redirect-based SCA over decoupled when set to `true`. The bank may not support both types. | | `PSU-IP-Address` | string(ipv4) | The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU. | | `PSU-User-Agent` | string | The forwarded Agent header field of the HTTP request between PSU and TPP, if available. | #### Request Body | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------- | | `authenticationMethodId` | string | The ID of the authentication method provided by the bank. | ```bash curl -X PUT "https://api.openbankingplatform.com/{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "X-Request-ID: 57d92dd1-077a-4425-bd9e-e69e1079d107" \ -H "X-BicFi: ESSESESS" \ -H "PSU-ID: 199002092386" \ -H "PSU-Corporate-ID: 5560160680" \ -H "TPP-Redirect-Preferred: false" \ -H "PSU-IP-Address: 152.120.171.187" \ -H "PSU-User-Agent: mozilla/5.0" -d '{ "authenticationMethodId": "mbid_animated_qr_token" }' ``` The first thing to check in the response is the SCA flow used by the bank, which will be extracted from the response header `aspsp-sca-approach`. For a decoupled flow, `aspsp-sca-approach` should be `DECOUPLED`, in which case you will need to present the correct interface to the PSU. #### Response Headers ```json aspsp-sca-approach: "DECOUPLED" ``` **A. If `authenticationMethodId` is `mbid_same_device` or `mbid`:** These methods launch the BankID app on the same device, meaning that you need to generate the BankID link. To do this, you first need to get the `data` from the response, which you will set the `{autoStartToken}` to in the BankID link. #### Response ```json { "chosenScaMethod": { "authenticationType": "CHIP_OTP", "authenticationMethodId": "mbid_same_device", "name": "Mobile BankID on this device" }, "_links": { "scaStatus": { "href": "/{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb" } }, "scaStatus": "started", "challengeData": { "data": [ "0a5f9137-7cb2-4d2f-b762-bfab4ad9d35f" ] } } ``` Once you have the `{autoStartToken}`, the BankID link should be constructed as below: ```text https://app.bankid.com/?autostarttoken={autoStartToken}&redirect={redirectUriAfterDecoupledAuthentication} ``` If your PSUs only use desktop, set `{redirectUriAfterDecoupledAuthentication}` to null: ```text https://app.bankid.com/?autostarttoken=0a5f9137-7cb2-4d2f-b762-bfab4ad9d35f&redirect=null ``` If your PSUs are on mobile or mixed device types, set `{redirectUriAfterDecoupledAuthentication}` to the URI that the PSU should be redirected to after authenticating: ```text https://app.bankid.com/?autostarttoken=0a5f9137-7cb2-4d2f-b762-bfab4ad9d35f&redirect=https://exampleapplication.com/callback ``` **B. If `authenticationMethodId` is `mbid_animated_qr_token`:** With this method, you need to generate your own QR code from the token `animatedQRToken` and instruct the PSU to scan it in the Mobile BankID app. :::warning The QR code is only valid for 1 second and must be refreshed by polling Get Authorisation SCA Status every 500-1000ms to give the PSU enough time to scan it. Only send a new request when you've received a response for the previous one. ::: #### Response ```json { "chosenScaMethod": { "authenticationType": "PHOTO_OTP", "authenticationMethodId": "mbid_animated_qr_token", "name": "Mobile BankID on another device" }, "_links": { "scaStatus": { "href": "/{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb" } }, "scaStatus": "started", "challengeData": { "data": [ "bankid.dXRvS2VuU3RyaW5nMTIz" ] } } ``` **C. If `authenticationMethodId` is `mbid_animated_qr_image`:** With this method, you need to dispay the Base64-encoded PNG `animatedQRImage` and instruct the PSU to scan it in the Mobile BankID app. #### Response ```json { "chosenScaMethod": { "authenticationType": "PHOTO_OTP", "authenticationMethodId": "mbid_animated_qr_image", "name": "Mobile BankID on another device" }, "_links": { "scaStatus": { "href": "/{resourceBasePath}/10f647b2-2ec3-48a5-845b-c3851cde1acb" } }, "psuMessage": "Please confirm with your bank app.", "scaStatus": "started", "challengeData": { "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA" } } ``` ### 3. Get Authorisation SCA Status Finally, use the `scaStatus` link from the response to poll the Get Authorisation SCA Status call until `scaStatus` becomes `finalised` or `failed`. :::info Authentication may take time. Keep polling Get Authorisation SCA Status until a final status is returned. **Sandbox:** The status transitions automatically within a few seconds, with no PSU action required. ::: #### Endpoint ```http GET {resourceBasePath}/authorisations/{authorisationId} ``` #### Path Parameters | Name | Type | Description | | ----------------- | ------ | ----------------------------------------------------- | | `authorisationId` | string | The ID of the authorisation process that was created. | #### Request Headers | Name | Type | Description | | ------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------- | | `X-Request-ID` | string(uuid) | The ID of the request, unique to the call, as determined by the initiating party. | | `X-BicFi` | string | The BIC of the bank to which the request is addressed. | | `PSU-ID` | string | The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID. | | `PSU-Corporate-ID` | string | The Corporate ID of the PSU when acting on behalf of an organisation, e.g. Org. nummer for SE, KVK for NL. | | `TPP-Redirect-Preferred` | boolean | Indicates a preference for redirect-based SCA over decoupled when set to `true`. The bank may not support both types. | | `PSU-IP-Address` | string(ipv4) | The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU. | | `PSU-User-Agent` | string | The forwarded Agent header field of the HTTP request between PSU and TPP, if available. | ```bash curl -X GET "https://api.openbankingplatform.com/{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb" \ -H "Authorization: Bearer " \ -H "X-Request-ID: 9d443655-c1e9-4434-9013-56a859bb8b67" \ -H "X-BicFi: ESSESESS" \ -H "PSU-ID: 199002092386" \ -H "PSU-Corporate-ID: 5560160680" \ -H "TPP-Redirect-Preferred: false" \ -H "PSU-IP-Address: 152.120.171.187" \ -H "PSU-User-Agent: mozilla/5.0" ``` #### Response ```json { "scaStatus": "finalised" } ``` --- ## Redirect Flow :::warning The redirect flow is available in production only. Use the [decoupled flow](#decoupled-flow) when testing in sandbox. ::: ### 1. Create Authorisation The first step after creating a resource is to create an authorisation process for that resource. The response will provide a list of available SCA methods for the specified bank. #### Endpoint ```http POST /{resourceBasePath}/authorisations ``` #### Request Headers | Name | Type | Description | | ------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------- | | `X-Request-ID` | string(uuid) | The ID of the request, unique to the call, as determined by the initiating party. | | `X-BicFi` | string | The BIC of the bank to which the request is addressed. | | `PSU-ID` | string | The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID. | | `PSU-Corporate-ID` | string | The Corporate ID of the PSU when acting on behalf of an organisation, e.g. Org. nummer for SE, KVK for NL. | | `TPP-Redirect-Preferred` | boolean | Indicates a preference for redirect-based SCA over decoupled when set to `true`. The bank may not support both types. | | `PSU-IP-Address` | string(ipv4) | The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU. | | `PSU-User-Agent` | string | The forwarded Agent header field of the HTTP request between PSU and TPP, if available. | ```bash curl -X POST "https://api.openbankingplatform.com/{resourceBasePath}/authorisations" \ -H "Authorization: Bearer " \ -H "X-Request-ID: 6c2fd2da-d90e-4cc9-944b-0e470594540d" \ -H "X-BicFi: ESSESESS" \ -H "PSU-ID: 199002092386" \ -H "PSU-Corporate-ID: 5560160680" \ -H "TPP-Redirect-Preferred: true" \ -H "PSU-IP-Address: 152.120.171.187" \ -H "PSU-User-Agent: mozilla/5.0" ``` #### Response ```json { "authorisationId": "10f647b2-2ec3-48a5-845b-c3851cde1acb", "scaStatus": "received", "scaMethods": [ { "authenticationType": "PUSH_OTP", "authenticationMethodId": "mbid", "name": "Mobilt BankID" } ], "_links": { "authoriseTransaction": { "href": "/{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb" }, "scaStatus": { "href": "/{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb" } } } ``` ### 2. Start Authorisation This request triggers the authentication flow. Here, you select the appropriate SCA method for the PSU's context and initiate the authentication process. This is done by taking the `authenticationMethodId` of an SCA method listed in the previous step and including it in the request body. For a redirect flow, `authenticationMethodId` is always `mbid`. #### Endpoint ```http PUT /{resourceBasePath}/authorisations/{authorisationId} ``` #### Path Parameters | Name | Type | Description | | ----------------- | ------ | ----------------------------------------------------- | | `authorisationId` | string | The ID of the authorisation process that was created. | #### Request Headers | Name | Type | Description | | ------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------- | | `X-Request-ID` | string(uuid) | The ID of the request, unique to the call, as determined by the initiating party. | | `X-BicFi` | string | The BIC of the bank to which the request is addressed. | | `PSU-ID` | string | The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID. | | `PSU-Corporate-ID` | string | The Corporate ID of the PSU when acting on behalf of an organisation, e.g. Org. nummer for SE, KVK for NL. | | `TPP-Redirect-Preferred` | boolean | Indicates a preference for redirect-based SCA over decoupled when set to `true`. The bank may not support both types. | | `PSU-IP-Address` | string(ipv4) | The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU. | | `PSU-User-Agent` | string | The forwarded Agent header field of the HTTP request between PSU and TPP, if available. | #### Request Body | Name | Type | Description | | ------------------------ | ------ | --------------------------------------------------------- | | `authenticationMethodId` | string | The ID of the authentication method provided by the bank. | ```bash curl -X PUT "https://api.openbankingplatform.com/{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "X-Request-ID: 57d92dd1-077a-4425-bd9e-e69e1079d107" \ -H "X-BicFi: ESSESESS" \ -H "PSU-ID: 199002092386" \ -H "PSU-Corporate-ID: 5560160680" \ -H "TPP-Redirect-Preferred: true" \ -H "PSU-IP-Address: 152.120.171.187" \ -H "PSU-User-Agent: mozilla/5.0" \ -d '{ "authenticationMethodId": "mbid" }' ``` #### Response Headers ```json aspsp-sca-approach: "REDIRECT" ``` If the `aspsp-sca-approach` is `REDIRECT`, the PSU will authenticate via the bank’s external authentication page. As the TPP, you need to extract the redirect link from the `scaOAuth` parameter and replace the placeholders with the relevant values. #### Response ```json { "chosenScaMethod": { "authenticationType": "PUSH_OTP", "authenticationMethodId": "mbid", "name": "Mobilt BankID" }, "_links": { "scaStatus": { "href": "/{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb" }, "scaOAuth": { "href": "https://auth.openbankingplatform.com/connect/authorize?client_id=[CLIENT_ID]&scope={resourceScope}&response_type=code&redirect_uri=[TPP_REDIRECT_URI]&state=[TPP_STATE]&acr_values=idp:ESSESESS%20{resource}Id:70c6d203-e1d1-43ff-9e42-07e5dda640ba%20{ResourceType}AuthorisationId:10f647b2-2ec3-48a5-845b-c3851cde1acb" } }, "scaStatus": "started" } ``` Replace the following placeholders in the redirect link as below: `[CLIENT_ID]` should be replaced by the `client_id` of your application in the Developer Portal. `[TPP_REDIRECT_URI]` is the URI you want us to redirect to after you get confirmation from the bank that the PSU has authenticated. This URI has to be whitelisted for your application in the Developer Portal. `[TPP_STATE]` is a convenience field for you to put in a value of your choice that identifies this session. It's important that you can identify the correct session after the PSU is redirected back again. Now that you have what you need to let the PSU authenticate, redirect the PSU to this URI. When the PSU has authenticated, the bank will route the PSU back to your `[TPP_REDIRECT_URI]`. Once the PSU has been redirected, a `code` will be added to the URI, which you will need to extract in the following step, along with the `scope`. ```text https://www.openpayments.io/?code=AMpzr91kT-QwL8dXyNf3VbGt6hEsJoRc2mKuHqPaSj&scope={resourceScope}&state=myState ``` ### 2.1 Activate OAuth Authorisation To finalise the authorisation, you make the following request to our auth server. #### Endpoint ```http POST /connect/token ``` #### Request Headers | Name | Type | Description | | --------------------------------- | ------ | ----------------------------------------------------- | | `X-{resource}Id` | string | The ID of the resource that was created. | | `X-{ResourceType}AuthorisationId` | string | The ID of the authorisation process that was created. | #### Request Body | Name | Type | Description | | --------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `client_id` | string | The Client ID of the application you created in the Developer Portal. | | `client_secret` | string | The secret key that was generated when the application was created. | | `code` | string | The authorisation code received from the authorisation server after the PSU has authenticated at the bank. This code is exchanged for an access token. | | `redirect_uri` | string(uri) | The URI to which the PSU was redirected after authorisation. It must exactly match the redirect URI used in the initial authorisation request. | | `scope` | string | Specifies the level of access requested. It is a space-separated string combining API scopes (e.g. `accountinformation`) and PSU context scopes (e.g. `corporate`). | | `grant_type` | string(enum) | Specifies the OAuth 2.0 grant flow to use. For redirect-based access tokens, this should be `authorization_code`. | ```bash curl -X POST "https://auth.openbankingplatform.com/connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -H "X-{resource}Id: 70c6d203-e1d1-43ff-9e42-07e5dda640ba" \ -H "X-{ResourceType}AuthorisationId: 10f647b2-2ec3-48a5-845b-c3851cde1acb" \ -d "client_id=555510ad-da62-4e6d-80b8-e18967eabf0b" \ -d "client_secret=joiaHR0cHM6Ly9hdXRoLm9wZW5iYW5raW5ncGxhdGZvcm0uY29tIiwiYXVkIjpb" \ -d "code=AMpzr91kT-QwL8dXyNf3VbGt6hEsJoRc2mKuHqPaSj" \ -d "redirect_uri=https://exampleapplication.com/callback" \ -d "scope={resourceScope}" \ -d "grant_type=authorization_code" ``` #### Response ```json { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIn0...", "expires_in": 3600, "token_type": "Bearer", "scope": "{resourceScope}" } ``` :::note If you receive an access token it means that the request was successful. This access token does **not** need to be stored or used in any subsequent calls. ::: ### 3. Get Authorisation SCA Status Regardless of the method, you can use the `scaStatus` link from the response to poll the Get Authorisation SCA Status call until `scaStatus` becomes `finalised` or `failed`. :::info Authentication may take time. Keep polling Get Authorisation SCA Status until a final status is returned. ::: #### Endpoint ```http GET /{resourceBasePath}/authorisations/{authorisationId} ``` #### Path Parameters | Name | Type | Description | | ---------------------------- | ------ | ----------------------------------------------------- | | `authorisationId` | string | The ID of the authorisation process that was created. | #### Request Headers | Name | Type | Description | | ------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------- | | `X-Request-ID` | string(uuid) | The ID of the request, unique to the call, as determined by the initiating party. | | `X-BicFi` | string | The BIC of the bank to which the request is addressed. | | `PSU-ID` | string | The ID used to identify the PSU at the bank. Typically a local social security number or another unique login ID. | | `PSU-Corporate-ID` | string | The Corporate ID of the PSU when acting on behalf of an organisation, e.g. Org. nummer for SE, KVK for NL. | | `TPP-Redirect-Preferred` | boolean | Indicates a preference for redirect-based SCA over decoupled when set to `true`. The bank may not support both types. | | `PSU-IP-Address` | string(ipv4) | The IP address of the PSU to be forwarded to the bank. Only included if the request was actively initiated by the PSU. | | `PSU-User-Agent` | string | The forwarded Agent header field of the HTTP request between PSU and TPP, if available. | ```bash curl -X GET "https://api.openbankingplatform.com/{resourceBasePath}/authorisations/10f647b2-2ec3-48a5-845b-c3851cde1acb" \ -H "Authorization: Bearer " \ -H "X-Request-ID: 9d443655-c1e9-4434-9013-56a859bb8b67" \ -H "X-BicFi: ESSESESS" \ -H "PSU-ID: 199002092386" \ -H "PSU-Corporate-ID: 5560160680" \ -H "TPP-Redirect-Preferred: true" \ -H "PSU-IP-Address: 152.120.171.187" \ -H "PSU-User-Agent: mozilla/5.0" ``` #### Response ```json { "scaStatus": "finalised" } ```