Consent API

Get required access tokens to call Account APIs

Introduction

These APIs provide the possibility to bootstrap the consent flow [for AIS] and retrieve the tokens [for AIS/PIS].

Consumes
  • application/json
Produces
  • application/json

Hosts

You can use the production host when you want to go live:

https://psd2.b2b.belfius.be:8443

Click the button below to download the open API specification.

Download

Example screen

Navigate to an endpoint to see sample code


Get consent uris.

Fetch the possible uris in order to start the consent flow for AIS. TPPs will first have to do a GET /consent-uris and a POST /token before being able to call the effective AIS APIs. If the matching language is provided [via Accept-Language header], corresponding consent-uri would be returned. In the absence of valid language, all of the available consent-uri's for this client would be returned, which means client himself has to choose the appropriate consent-uri for it's type of device in order to start the actual flow. Note that scope (AIS) is implicit in the response due the AIS nature of this API.


Parameters

Response

[
  {
    "language": "fr",
    "consent_uri": "https://www.belfius.be/common/fr/fw/generic/launcher.html?appkey=APP_KEY&apptoken=rdger6e5325drte5635trwe45rew5wr345we5"
  }
]
Possible responses
ScenarioResponse
Request received without a mandatory parameter
 {
 "error": "missing_input",
 "error_code": "10001", 
 "error_description": "Missing required input 'INPUT'. DETAILS OF WHAT IS WRONG." 
}
Request received with bad parameters (invalid format) values
 {
 "error": "invalid_input",
 "error_code": "10002",
 "error_description": "Input 'INPUT' is not valid. DETAILS OF WHAT IS WRONG." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
Request received with invalid values for Oauth2 Security related parametes
 {
 "error": "failed_security_validation",
 "error_code": "10003",
 "error_description": "Validation failed for security related parameters. DETAILS OF WHAT IS WRONG." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
Request received with a Client-ID(TPPID) which is not active
 {
 "error": "blocked_tpp",
 "error_code": "20001", 
 "error_description": "No Active TPP found." 
}
Request received with non-belfius account
 {
 "error": "invalid_account",
 "error_code": "20002",
 "error_description": "No Account found." 
}
Request received with account 'not consultable with electronic channel'
 {
 "error": "channel_not_permitted",
 "error_code": "20003",
 "error_description": "This account can not be consultated via electronical channel." }
Request received with account 'not allowed for PSD2'
 {
 "error": "account_not_supported",
 "error_code": "20004",
 "error_description": "This account is not allowed for this type of request." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
Request received with invalid version in Accept header
 {
 "error": "resource_not_found",
 "error_code": "10004",
 "error_description": " Specific version not found.  Supported versions are [X,..]." 
}
Request received with unsupported HTTP verb
 {
 "error": "resource_not_found",
 "error_code": "10102",
 "error_description": " Requested resource was not found." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
Request received with restricted HTTP verbs
 {
 "error": "method_not_allowed",
 "error_code": "10103",
 "error_description": " Requested HTTP method is not allowed for this api." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
Request received with invalid type in Accept header
 {
 "error": "unacceptable_media_type",
 "error_code": "10005",
 "error_description": " Server can not return the response In the format mentioned in the request. Supported type is application/vnd.belfius.api+json;." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
Client request exceed the configured Quota limit for the associated Account Plan
 {
 "error": "quota_limit_exceeded",
 "error_code": "10105", 
 "error_description": " Quota limit exceed." 
}
Client request exceed the configured Quota limit for the associated API Plan
 {
 "error": "quota_limit_exceeded",
 "error_code": "10106",
 "error_description": " Quota limit exceed." 
}
Client request exceeded the configured rate limit
 {
 "error": "rate_limit_exceeded",
 "error_code": "10107",
 "error_description": " Rate limit exceed." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
SSL certificate error
 {
 "error": "ssl_validation_error",
 "error_code": "10020",
 "error_description": "error during client authentication." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
Internal server error
 {
 "error": "internal_server_error",
 "error_code": "20020", 
 "error_description": " Internal error occurred." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
Client request falls in the configured 'restrict time period' frame
 {
 "error": "service_unavailable",
 "error_code": "10108",
 "error_description": " Service unavailable, please try after some time." 
}
Client request falls in the configured 'restrict day period' frame
 {
 "error": "service_unavailable",
 "error_code": "10109",
 "error_description": " Service unavailable, please try in 24 hours." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Get /consent-uris

Request example

There is no example request provided

Response example

[
  {
    "language": "fr",
    "consent_uri": "https://www.belfius.be/common/fr/fw/generic/launcher.html?appkey=APP_KEY&apptoken=rdger6e5325drte5635trwe45rew5wr345we5"
  }
]
{
 "error": "missing_input",
 "error_code": "10001", 
 "error_description": "Missing required input 'INPUT'. DETAILS OF WHAT IS WRONG." 
}
{
 "error": "invalid_input",
 "error_code": "10002",
 "error_description": "Input 'INPUT' is not valid. DETAILS OF WHAT IS WRONG." 
}
{
 "error": "failed_security_validation",
 "error_code": "10003",
 "error_description": "Validation failed for security related parameters. DETAILS OF WHAT IS WRONG." 
}
{
 "error": "blocked_tpp",
 "error_code": "20001", 
 "error_description": "No Active TPP found." 
}
{
 "error": "invalid_account",
 "error_code": "20002",
 "error_description": "No Account found." 
}
{
 "error": "channel_not_permitted",
 "error_code": "20003",
 "error_description": "This account can not be consultated via electronical channel." }
{
 "error": "account_not_supported",
 "error_code": "20004",
 "error_description": "This account is not allowed for this type of request." 
}
{
 "error": "resource_not_found",
 "error_code": "10004",
 "error_description": " Specific version not found.  Supported versions are [X,..]." 
}
{
 "error": "resource_not_found",
 "error_code": "10102",
 "error_description": " Requested resource was not found." 
}
{
 "error": "method_not_allowed",
 "error_code": "10103",
 "error_description": " Requested HTTP method is not allowed for this api." 
}
{
 "error": "unacceptable_media_type",
 "error_code": "10005",
 "error_description": " Server can not return the response In the format mentioned in the request. Supported type is application/vnd.belfius.api+json;." 
}
{
 "error": "quota_limit_exceeded",
 "error_code": "10105", 
 "error_description": " Quota limit exceed." 
}
{
 "error": "quota_limit_exceeded",
 "error_code": "10106",
 "error_description": " Quota limit exceed." 
}
{
 "error": "rate_limit_exceeded",
 "error_code": "10107",
 "error_description": " Rate limit exceed." 
}
{
 "error": "ssl_validation_error",
 "error_code": "10020",
 "error_description": "error during client authentication." 
}
{
 "error": "internal_server_error",
 "error_code": "20020", 
 "error_description": " Internal error occurred." 
}
{
 "error": "service_unavailable",
 "error_code": "10108",
 "error_description": " Service unavailable, please try after some time." 
}
{
 "error": "service_unavailable",
 "error_code": "10109",
 "error_description": " Service unavailable, please try in 24 hours." 
}

Create access/refresh tokens.

Token endpoint provides the possibility to get an access-token +optionally refresh token, as well as to get a refresh token which could be used to get a new access-token. It reacts based on grant_type which can be 'authorization_code' or 'refresh_token'.


Request

Both payloads are valid requests, do not use them in the same request.

Name Type Description
grant_type string Which grant types the client will use to get tokens. - authorization_code: The authorization code grant, where the client sends the resource owner to the authorization endpoint to obtain an authorization code, then presents that code back to the token endpoint. Needs to be used with the “code” response_type. - refresh_token: The refresh token grant, where the client uses a refresh token to obtain a new access token when the resource owner is no longer present
code string authorzation code received perviously from authorization server.
redirect_uri string URI string used in redirect-based OAuth grants, such as authorization_code and implicit. Must be equal to the one provided during the authorization code / implicit request.
code_verifier string PKCE code verifier as per RFC https://tools.ietf.org/html/rfc7636.
grant_type string Which grant types the client will use to get tokens. - authorization_code: The authorization code grant, where the client sends the resource owner to the authorization endpoint to obtain an authorization code, then presents that code back to the token endpoint. Needs to be used with the “code” response_type. - refresh_token: The refresh token grant, where the client uses a refresh token to obtain a new access token when the resource owner is no longer present
refresh_token string Original refresh token provided by authorization server to the client at the time of authorization & consent.
scope string Optional. The scope of the access request. The requested scope MUST NOT include any scope not originally granted by the resource owner (although it can reduce that scope), and if omitted is treated as equal to the scope originally granted by the resource owner

Parameters

Response

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "id_token": "fghGzv3JOkF0XG5Qx2TlKRsd",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "AIS",
  "logical_id": "aDfGzv3JOkF0XG5Qx2TlKRft"
}
Possible responses
ScenarioResponse
Request received without a mandatory parameter
 {
 "error": "missing_input",
 "error_code": "10001",
 "error_description": "Missing required input 'INPUT'. DETAILS OF WHAT IS WRONG." 
}
Request received with bad parameters (invalid format) values
 {
 "error": "invalid_input",
 "error_code": "10002",
 "error_description": "Input 'INPUT' is not valid. DETAILS OF WHAT IS WRONG." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
Request received with invalid values for Oauth2 Security related parametes
 {
 "error": "failed_security_validation",
 "error_code": "10003",
 "error_description": "Validation failed for security related parameters. DETAILS OF WHAT IS WRONG." 
}
Request received with Authorization-header containing client-id which is different than the one used to create authorization code
 {
 "error": "unauthorized_client",
 "error_code": "10019",
 "error_description": "The client misses authorization for this request." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
Request received with unsupported Content-Type Header
 {
 "error": "unsupported_media_type",
 "error_code": "10012", 
 "error_description": "Content-Type must be application/json." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
Client request exceed the configured Quota limit for the associated Account Plan
 {
 "error": "quota_limit_exceeded",
 "error_code": "10105",
 "error_description": " Quota limit exceed." 
}
Client request exceed the configured Quota limit for the associated API Plan
 {
 "error": "quota_limit_exceeded",
 "error_code": "10106",
 "error_description": " Quota limit exceed." 
}
Client request exceeded the configured rate limit
 {
 "error": "rate_limit_exceeded",
 "error_code": "10107",
 "error_description": " Rate limit exceed." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
SSL certificate error
 {
 "error": "ssl_validation_error",
 "error_code": "10020",
 "error_description": "error during client authentication." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
Internal server error
 {
 "error": "internal_server_error",
 "error_code": "20020",
 "error_description": " Internal error occurred." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Possible responses
ScenarioResponse
Client request falls in the configured 'restrict time period' frame
 {
 "error": "service_unavailable",
 "error_code": "10108",
 "error_description": " Service unavailable, please try after some time." 
}
Client request falls in the configured 'restrict day period' frame
 {
 "error": "service_unavailable",
 "error_code": "10109",
 "error_description": " Service unavailable, please try in 24 hours." 
}

  • Fixed-form error tokens mapping to specific errors.

    error (string)

  • Error specific code, could be used directly by consumer's software.

    error_code (string)

  • Full description of the error.

    error_description (string)

Post /token

Request example

{
  "grant_type": "authorization_code",
  "code": "25sdfsdfsd5345",
  "redirect_uri": "https://localhost:9000/callback",
  "code_verifier": "sfs353DRT345D"
}

Response example

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "id_token": "fghGzv3JOkF0XG5Qx2TlKRsd",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "AIS",
  "logical_id": "aDfGzv3JOkF0XG5Qx2TlKRft"
}
{
 "error": "missing_input",
 "error_code": "10001",
 "error_description": "Missing required input 'INPUT'. DETAILS OF WHAT IS WRONG." 
}
{
 "error": "invalid_input",
 "error_code": "10002",
 "error_description": "Input 'INPUT' is not valid. DETAILS OF WHAT IS WRONG." 
}
{
 "error": "failed_security_validation",
 "error_code": "10003",
 "error_description": "Validation failed for security related parameters. DETAILS OF WHAT IS WRONG." 
}
{
 "error": "unauthorized_client",
 "error_code": "10019",
 "error_description": "The client misses authorization for this request." 
}
{
 "error": "unsupported_media_type",
 "error_code": "10012", 
 "error_description": "Content-Type must be application/json." 
}
{
 "error": "quota_limit_exceeded",
 "error_code": "10105",
 "error_description": " Quota limit exceed." 
}
{
 "error": "quota_limit_exceeded",
 "error_code": "10106",
 "error_description": " Quota limit exceed." 
}
{
 "error": "rate_limit_exceeded",
 "error_code": "10107",
 "error_description": " Rate limit exceed." 
}
{
 "error": "ssl_validation_error",
 "error_code": "10020",
 "error_description": "error during client authentication." 
}
{
 "error": "internal_server_error",
 "error_code": "20020",
 "error_description": " Internal error occurred." 
}
{
 "error": "service_unavailable",
 "error_code": "10108",
 "error_description": " Service unavailable, please try after some time." 
}
{
 "error": "service_unavailable",
 "error_code": "10109",
 "error_description": " Service unavailable, please try in 24 hours." 
}