• Interactive application is an application that involves user interaction. Such applications are getting authenticated into the DTCC DA platform when an actual human user provide their login credentials.

• Non-interactive application is an application that is involves server-to-server communication with the DTCC DA APIs. Such applications are normally used for automating API interactions between external applications without frontend and the DTCC DA platform, instead of having a real user at keyboard that performs those API requests manually. Non-interactive applications use service accounts to get authenticated into the DTCC DA platform.

• Service account is a machine user which is used by non-interactive applications for authenticating into the DTCC DA platform. In LedgerScan MVP service accounts use email and password login credentials, as a normal user.

Authentication with service accounts uses the Default Application client that is automatically created for each tenant. This aspect is not visible for end users and simplifies the UX of integrating external non-interactive applications.

To integrate your interactive application, first create an application client for a workspace you want to use for connecting to the LedgerScan APIs. This can be done on the Workspace Details page using button “New”. The following information is required for creating an application client for integrating an interactive application:

1. Name: Custom identifier for an application client. [200 character limit]
2. RedirectUris: URI location to which users are redirected after successfully completing the registration. [list of URIs, 400 character limit]
3. ReturnUris: URI location to which users are redirected after successfully completing the authentication. [ list of URIs, 2000 character limit]
4. PostLogoutRedirectUris: The location to which users get returned after logging out. [list of URIs, 400 character limit]
5. AllowedCorsOrigins: The collection of origins for cross-origin calls. [150 character limit]

In order to authenticate a user via the client application you’ve created, take the following steps:

1. Call GET {idt-baseUrl}/connect/authorize sending
1. client_id = {clientId}
2. response_type=code
3. redirect_uri = {redirectUri}
4. code_challenge = the SHA256 over the PKCE code. For saftey reasons, PKCE must be a random generated string. This is usually handled by the OAuth / OIDC library
5. code_challenge_method = S256
6. response_mode = query
7. scope = “openid profile offline_access” Note: This url will automatically redirect the user to IDT, where login will happen. Authorize endpoint documentation: https://docs.duendesoftware.com/identityserver/v6/reference/endpoints/authorize/
2. After the IDT Login interface is loaded, provide
1. Valid email and password credentials
2. Click Login Note: This will generate an authentication cookie, and redirects will happen. At the end of the flow, the authorization_code is generated and the user is redirected to DevPortal / redirect_uri with the authorization_code in the query string.
3. Call POST {idt-baseUrl}/connect/token using x-www-form-urlencoded content encoding type and sending the following parameters in the body:
1. client_id = {clientId}
2. grant_type = authorization_code
3. code = {authorization_code}
4. code_verifier = {the clear text PKCE code}
5. redirect_uri = {link to Athlon Developer Portal, where the authorization code will be handled} Note: Token endpoint documentation: https://docs.duendesoftware.com/identityserver/v6/reference/endpoints/token/

Service account management

To connect your non-interactive application, first create a service account via LedgerScan user interface. You will need the “Service account admin” function assigned.

Service accounts are using regular email and password credentials.

• The field “Name” is a custom identifier of a service account.
• Email IDs for service account creation do not have to be verified and it is recommended to use a dummy email.
• You will not be able to retrieve the password of service account after creating it. Please save the password in a safe external location.
• Password requirements:
• minimum of 10 characters (no more than 32) in length
• must contain at least one uppercase letter, one lowercase letter, one number and one of the following symbols: !@#$%&?
• Coming soon: support for new credentials types that will provide a better user experience for the service account management.

To enable your application that will use the service account to access APIs in your workspace, you need to assign functions to it. A user with the “Entity Admin” function can do that via the “Service Accounts” section available in the side menu.

• Functions assigned to a service account will define functionality your application can access.
• Coming soon: alternatively a user with “Service account view” function can delegate functions available to them to any service account.

When your service account is created and has functions chosen by you assigned, you can add its credentials in your application configuration to enable it to get authorized into the DTCC DA platform.

• For accessing DTCC DA platform all service accounts are using a default workspace client application which means you don’t need to create one for integrating non-interactive applications.

Access tokens for Service Accounts

To authorize under a Service Account authority `connect/token` endpoint should be used. This is a POST endpoint, which requires a set of parameters to be sent as a x-www-form-urlencoded:

The endpoint is responding in JSON format with an access_token which should be used to act under Service Account authority

Request Body

• grant_type:urn:dtcc:params:oauth:grant-type:service-account-credentials
• username: {email}
• password: {password}
• type:assignment
• acr_values:tenant:{tenantId}

Response Body

{

"access_token": “jwt_token”,

"expires_in": 86400,

"token_type": "Bearer",

"refresh_token": “refresh_token”,

"scope": "offline_access openid"

}