API Documentation - Raidiam Trust Platform

The Raidiam Trust Platform is a comprehensive technology suite designed to create and manage secure data-sharing ecosystems. Raidiam APIs provides all the necessary tools for organizations, consortiums, and governments to establish, secure, and control their own data-sharing environments.

Raidiam Trust Platform APIs enable participants to retrieve information stored within the platform, facilitating secure and efficient data sharing across the ecosystem. These APIs are crucial for discovering available participants, technical resources like authorization servers or published APIs, and public keys.

API Types

Raidiam Trust Platform offers two types of APIs, each serving distinct purposes:

• Public APIs: Publicly accessible endpoints, which do not require mTLS, serve general discovery purposes by allowing participants to gather non-sensitive information, such as participant details and public keys.

• Protected APIs: These endpoints require an mTLS connection to ensure a secure interaction and are used when accessing sensitive data. Access to these APIs is granted after obtaining an access token as part of the authentication flow.

Public APIs

Public APIs are endpoints that don't require authentication, allowing any application to interact with them without using a TLS certificate or undergoing OAuth 2.0 authentication.

API	Usage	Consumption Recommendation
Participants	Explore Data Provider Information: View a complete list of authorization servers for data providers, including detailed information on available API resources and server certifications. Up-to-Date and Relevant Information: Only operational organisations and servers are included, ensuring the data is accurate and reflects the most recent status. Highlight Active Authorisation Servers: The list exclusively features organisations with functioning authorization servers, providing a clear and up-to-date view of available participants.	The /participants endpoint should be used preferentially over restricted APIs such as /authorisationservers or /apiresources for data discovery. Since /participants provides comprehensive information about active participants, including their authorisation servers and resources, it reduces the need for additional calls to restricted endpoints and provides a simpler, non-mTLS secured method to gather the required details. The information in the /participants endpoint is reloaded every 15 minutes. Given this update frequency, it is recommended to cache the data locally rather than making repeated requests more frequently than necessary.
Keystores	Each ecosystem in Raidiam Trust Platform has its own public keystores deployed including: software-level transport and signing keystores, organisation-level signing and transport keystores, and more. Example: Sandbox Keystore.	The keys presented on the keystores should be cached as their information only changes when a certificate is revoked or added. Accessing keystore endpoints should align with your institution's risk policy, but maintaining a cache is important due to the high frequency with which signature validations are performed. Caching helps to minimize redundant requests and improve overall efficiency when verifying signatures and establishing secure connections.
API Resources	Provides information on all API resources available to an ecosystem for publication. This includes: Family Type: The name of the API resource Version: The available version of each API resource Expected URLs: The expected URL structure for each endpoint of the API resource	This endpoint should be called to verify details about the API Resources that can be registered on the Trust Framework, as well as their expected regular-expressions.
OpenID Discovery (/.well-known)	The .well-known/openid-configuration endpoint provides essential metadata about the Platform OP (OpenID Provider), including URLs for restricted APIs such as /token and /auth. Serves as the starting point for the authentication flow needed to interact with restricted APIs. Example: Sandbox /.well-known	This metadata rarely changes and is updated only in specific cases, such as the addition of new features or major configuration changes. Therefore, repeated calls to this endpoint are unnecessary.

info

The data provided by the public APIs changes very infrequently, typically only when significant updates are made.

Because of this, it is recommended to implement a caching strategy to avoid unnecessary calls to the above endpoints.

The cache duration should align with the max-age directive specified in the Cache-Control header (see the caching section for reference). The stable nature of this data supports efficient caching practices and reduces redundant requests, improving system performance.

Protected APIs

The mTLS-Protected APIs can only be accessed by Applications that have been registered with the Directory and hold valid TLS/Transport certificates issued by authorised Certificate Authorities (CAs) within the Directory.

To access these protected APIs, the participant must first generate an access token with the directory:software scope by calling the token endpoint using the client_credentials grant type. Instructions for obtaining an access token can be found on Client Credentials Flow: Obtain Access Token.

Authentication and Access

The authentication flow for restricted APIs starts with the /.well-known/openid-configuration endpoint, which provides the necessary metadata, including URLs for obtaining an access token (/token) and authorisation (/auth). Once the access token is retrieved, participants can use it to securely access restricted APIs.

After obtaining the access token, it can be used to access GET operations for all Trust Framework APIs that do not return personal data.

Examples of Protected APIs

Get All Organisations: Provides information about all organisations participating in the ecosystem.

Get Organisation Allows access to detailed information for a specific organisation identified by an {organisationId}.

These protected APIs provide sensitive and detailed information that is critical for secure and authorised data sharing within the ecosystem.

Cache Control

This section is applicable to all public endpoints (data.* and auth.*) and keystores, notably the participants and the well-known endpoint.

The Raidiam Trust Platform API responses include a Cache-Control header, which specifies caching directives for clients. For example:

Cache-Control: public, max-age=900

The above header indicates that:

• The response is cacheable by any cache (as it is marked public).

• The max-age=900 specifies that the response can be cached for 900 seconds (15 minutes) before a new request should be made.

Requirements

Acknowledge Cache-Control: Participants SHOULD respect the cache-control directives and implement local caching based on the max-age value.

Local Cache or Proxy: To comply with rate-limiting policies, participants are expected to utilize local caching mechanisms or organizational proxies.

Enforcement and Rate Limiting

Participants that execute a number of requests well above what’s expected based on the cache policy header may be rate limited by the Trust Framework services.

Best Practices for Raidiam API Usage

To ensure efficient and secure use of the Trust Platform APIs, adhere to the following best practices:

Public APIs Usage Best Practices

• Initial Data Discovery: Use the Participants API to gather general information, such as details on active participants and their endpoints, to avoid unnecessary use of restricted APIs.

• Effective Caching: Since the information provided by open APIs is mostly static, it is recommended to cache the data to reduce the frequency of API calls. For example, the /participants endpoint is updated every 15 minutes, and the .well-known/openid-configuration is also relatively static, so caching these endpoints helps balance system load and efficiency.

Protected APIs Usage Best Practices

• Use Only When Necessary: Restricted APIs require more resources due to mTLS connections. Use these only when secure interactions are required. For instance, use /authorisationservers only if the data required isn't available through the /participants endpoint, such as when looking for inactive authorisation servers, that are not returned in the later one.

• Optimize Connections: Implement persistent mTLS connections or use connection pooling to handle repeated requests to restricted APIs, reducing the overhead of repeated handshakes. Use exponential backoff to retry failed requests to avoid excessive load.

General Recommendations for Raidiam APIs

• Prioritise Open Data: Whenever possible, start with open APIs for data discovery to reduce the usage of restricted endpoints.

• Secure Caching: Safely store tokens and other sensitive data, respecting expiration policies to prevent unauthorised access.