Skip to main content

Conformance Suite APIs

This documentation aims to give a high-level Overview of the APIs implemented within the Conformance Suite that could be used by an Ecosystem Administrator to map details about what tests are being executed and what is their current execution status.

Admin Access​

Conformance Suite Admins the platform super users who are capable of accessing all test plans that have been created on the Platform, regardless of who has created them.

To be granted Admin Access on the Conformance Suite a Service Ticket must be raised on Jira with the e-mail address of the person who will receive this access. Once approved the corresponding user will

  • Receive an invitation to link/create an account on the Raidiam Azure domain

  • Be included in the corresponding privileged access group to access the platform

Admins are capable of viewing all created logs on the /logs.html page of the Conformance Suite U.I. and are also able to extract this log information both via the U.I. as well as a specific CS API, different from the regular user APIs.

Generating an Access Token Token​

All the APIs are protected using user-bound tokes, so the first step is to create an access token that can be used to call this API. To create a token, after authenticating add the following URI on your browser bar:

https\://info.conformance.\<host>, where \<host> is the address of the DNS provided to Raidiam for the Conformance Suite/Directory.

For Open Finance Brasil the DNS for the Directory is set as .directory.openbankingbrasil.org.br/ so the token page would be https://info.conformance.directory.openbankingbrasil.org.br/.

Once Logged you will be redirected to a page where you can see all your keys with the respective token.

To create a new token, you just need to choose an optional name for the key and click on the button "Create a new key", as shown in the image below;

Creating Key for Conformance Suite

Once created you will see the token created:

API key

This token will be used to authenticate on any of the Admin APIs.

Admin API - Test Plan List​

The Test Plan list API will return a list containing details about all the Active Test Plans, their Modules and general details about the test plan. The values on this API are returned in a JSON payload.

The Log Dump API uses the following API endpoint:

https://info.conformance.<host>/api/plans

An example of HTTPs request done using the generated token as a basic Authorization and pointing to the Open Finance Directory would be the following:

curl -X GET 'https://info.conformance.<host>/api/plans' -H 'Authorization: Bearer {Token_value}'

Admin API - Log Dump​

The Log Dump API is similar to the interaction on the UI where one can extract the Log information that is presented on the /logs.html CS page. Here is a list of executed test modules, general information about the test and their final status will be returned on a .csv format for the last 7 days.

The Log Dump API uses the following API endpoint:

https:// info.conformance.<host>/api/log/logs.csv

An example of HTTPs request done using the generated token as a basic Authorization and pointing to the Open Finance Directory would be the following:

curl -X GET 'https://info.conformance.<host>/api/log/logs.csv' -H 'Authorization: Bearer {Token_value}'

Conformance Suite - Failed Tests Log Dump​

This API returns a list of all Conformance Suite test modules that were not successfully completed. It provides detailed information to help identify and diagnose the cause of each test failure.

Response Fields​

FieldDescription
planIdUnique identifier of the test plan.
planNameName of the test plan.
testIdIdentifier of the executed test module.
startedDate and time when the test module was initiated.
statusFinal execution status of the test module.
Possible values:
  • FINISHED: Test module completed execution but encountered a failure.
  • INTERRUPTED: Test module was interrupted or failed before completing.
  • null: Test module stopped while awaiting redirection.
resultResult of the test module execution.
Possible values:
  • FAILED: A failure was detected during execution.
  • null: Execution did not complete due to redirection timeout or interruption.
discoveryUrlThe .well-known endpoint URL from the tested server.
brazilOrganizationIdThe organization ID of the tested server (as registered in Brazil’s directory).
msgError message generated by the Conformance Suite during test execution.

Notes​

A null value in status or result usually indicates that the test module was abandoned or did not complete due to an issue in the redirection flow.

The Failed Tests Log Dump API uses the following API endpoint:

GET https://info.conformance.directory.openbankingbrasil.org.br/api/metrics/failures

  • Authentication: Use your API Key as a Bearer token

  • Example tools: Postman, curl

  • Note: This endpoint supports pagination

Example curl command:

curl -X GET "https://info.conformance.directory.openbankingbrasil.org.br/api/metrics/failures" \
  -H "Authorization: Bearer <your_api_key>" \
  -H "accept: application/json"

Production Environments Access​

API access to the Production Testing Conformance Suite is similar to the one required for the Conformance Suite, with the only difference being the additional Web Application Firewall (WAF) rules that are included within this environment.

Endpoints for Production Environments are also slightly different, with a few examples named below:

  • https\://info.fvp.\<host>

  • https\://info.conftpp.\<host>

Note on User-Agent Requirement​

Raidiam Production Testing infrastructure has a Web Application Firewall (WAF) rule that might block certain requests, especially from tools like curl, due to the absence of the User-Agent header as a measure to prevent potential bot traffic.

While you can add a User-Agent header to bypass this restriction, it’s essential to understand that simply spoofing a common browser user-agent with curl is not a recommended long-term solution, especially for production-level integrations. Instead, ensure that whatever software or system integrating with this API sends appropriate, honest headers indicating its identity.

Most standard libraries and platforms used to make HTTP requests will include a default User-Agent header, which should not encounter this restriction. If you do face any issues or are blocked with a “403 - FORBIDDEN” error code, please ensure you are sending a valid User-Agent header.

End User APIs​

In Addition to the Regular Conformance Suite Admin APIs the Platform is also set with a series of APIs that can be accessed by the Regular, non-admin, user.

To access those APIs the users needs to be authenticated as Non-Admin user, so when using them you must not be logged in with admin access.

Once Authenticated as a Regular User on the Platform, prior to accessing the APIs you will need to generate an Access Token, which can be done on the UI on the page /tokens.html.

End User Token Management Page

To access the full documentation of the End User APIs go to the page /api-document.html, which will provide all the details of the APIs that can be called with the tokens created on the session above, as well as all the APIs that can be used to run conformance tests without interacting directly with the U.I.

Example - Test Plan API​

Following the session before, which talks about the end-user tokens and the api documentation, this session will aim to do a walk-throught on calling the Test Plan API. For this guide the Open Finance APIs will be used as an example, but this can be applied to any other environment by simply switching the host on the URI.

The first step on accessing this API is on creating a token to authorize the request. On the Token.html page both temporary (1 day expiration) and permanent (no expiration) tokens can be issued.

Access Tokens Page

Once you click on New temporary token or New permanent token a pop up appears on your screen with the token that is issued, as shown below.

danger

If you select Close, the token cannot be viewed anymore, so you should use it before closing the window.

To get information of all test plans available, you can make a request to the following endpoint:

https://web.conformance.<host>/api/plan/available

From this API you can find details of each test plan that can be created and executed on Conformance Suite, such as summary, all modules executed, profile type, and more.

An example of HTTP request would be:

curl -X GET "https://web.conformance.directory.openbankingbrasil.org.br/api/plan/available" -H "accept: application/json" -H "Authorization: Bearer {token}"

The same way you can get information of all test modules present in the Conformance Suite. Just make a request to the following endpoint:

https://web.conformance.<host>/api/runner/available

You will get details such as name, summary, profile, auth methods, configuration fields, and more.

An example of access from terminal:

curl -X GET "https://web.conformance.directory.openbankingbrasil.org.br/api/runner/available"  -H "accept: application/json" "Authorization: Bearer {token}"
Open Book IconTABLE OF CONTENT