3.3 Using Dynamic Client Registration (DCR) Endpoint Data

This page describes what you need to set for using the DCR endpoints. There are also guidelines on scopes that are required for the DCR endpoint. For details on the DCR endpoints in Postman, refer to the Cards API Website: Accessing Cards API with mTLS.

3.3.1 Adding Base URLs for DCR

For calling the DCR POST endpoint, you need to include the Base URLs within your REST tool, for example, Postman. The Base URLs are the hosts that accept the certificates. The Cards API, the API Hub, and Thredd CA hosts contain unique URLs, which can differ for UAT and Production. The Base URLs are as follows:

Cards API: https://api.uat.threddpay.com/api/v1
API Hub: https://uat-api.thredd.com
Thredd Certificate Authority: https://matls-auth.directory.sandbox.threddid.com

The following are used in Production.

API Hub: https://api.thredd.com/ (for all PRD environments)
Cards API: https://coreapi.threddpay.com

Adding Certificates to Hosts (Postman)

In Postman, you need to include the certificates with the individual hosts. Perform the following steps:

Click the gears icon and Settings.
Click Certificates from the left-hand menu.
Click Add Certificate.

Enter a host name.
Add CRT and Key files for the host.
Click the Add button.

For more details, refer to Cards API Website: Accessing the Cards API with mTLS.

3.3.2 Understanding Scopes in the DCR Endpoint

Depending on which Thredd Services you require, your Organisation will have been assigned a number of available Roles which can be chosen when you create your Application. The Scopes are what you can do for those Roles. The Scopes that you can register depend on the Roles your application is registered for. If you include more Scopes than are available for Roles, your application will not accept the new Scopes. This is because the Scopes you include depend on the Roles for the application.

For example, if you application includes the following "scopes":["bulkcard.read", "bulkcard.write" registered for the "bulk cards" role, then you cannot include additional Scopes in the request body. Adding a Scope such as “cards.write to the request body will not be accepted. The following shows an example of a DCR POST request.

Copy

{
  "grant_types":[
    "client_credentials"
  ],
  "application_types":[
    "service",
    "dcr"
  ],
  "application_type":"service",
  "token_endpoint_auth_method":"private_key_jwt",
  "id_token_signed_response_alg":"RS256",
  "scopes":[
    "3ds.read",
    "bulkcard.read",
    "bulkcard.write",
    "cards.encrypted",
    "cards.read",
    "cards.sensitive",
    "cards.write",
    "cvv.read",
    "cvv.write",
    "digitalchannel",
    "fraud.read",
    "fraud.write",
    "pin.read",
    "pin.write"
  ],
  "tls_client_certificate_bound_access_tokens":true,
  "request_object_signing_alg":"RS256",
  "response_types":"token",
  "software_statement":"{{ssa}}"
}

Setting a Role for a Scope

If your application requires a specific Scope, then you need to set the correct Role in Thredd Certificate Authority. When you have chosen the correct Role, you will see the Scope in the DCR request. The following example shows an application using the EDS Scopes of eds.read and eds.write when you select the eds Role in your application on the Thredd Certificate Authority.

For more details on the steps for creating REST certificates in the Thredd Certificate Authority dashboard, refer to Creating Client Application Certificates for REST APIs.

Click New Application.
The Roles for the application appear.

Select the Role, in this case eds and click Next.
When you run the DCR request, you will see the eds scopes. See the example below.

Copy

{
  "grant_types":[
    "client_credentials"
  ],
  "application_types":[
    "service",
    "dcr"
  ],
  "application_type":"service",
  "token_endpoint_auth_method":"private_key_jwt",
  "id_token_signed_response_alg":"RS256",
  "scopes":[
    "3ds.read",
    "bulkcard.read",
    "bulkcard.write",
    "cards.encrypted",
    "cards.read",
    "cards.sensitive",
    "cards.write",
    "eds.read",
    "eds.write",
    "cvv.read",
    "cvv.write",
    "digitalchannel",
    "fraud.read",
    "fraud.write",
    "pin.read",
    "pin.write"
  ],
  "tls_client_certificate_bound_access_tokens":true,
  "request_object_signing_alg":"RS256",
  "response_types":"token",
  "software_statement":"{{ssa}}"
}

Updating Roles and Scopes

If required, you can update the Roles of an Application and the Scopes that your OAuth Client has registered. You may need new Scopes, for example, if a new service is added to Thredd and the organisation requires them. New Scopes may be part of an existing or new Role.

This depends on if you have access to the following variables: registration_access_token and the registration_client_uri (for details on these variables refer to Identifying and Storing the registration_access_token and registration_client_uri Data). To add Roles or Scopes there are a number of workflows to do this.

For more details on the Postman steps refer to the Cards API Website: Access the Cards API with mTLS.

Once you have performed a DCR POST or DCR PUT for adding or updating a client, contact Thredd so that we can update your Programme Manager (or Issuer) metadata related to the newly-registered or updated OAuth client.

Thredd Deletes a Client and Customer Creates a New One

If you do not have access to the registration variables, you need to request Thredd to delete your existing OAuth Client. Once Thredd have deleted the OAuth Client, you can then create it again using the DCR POST request in Postman. Provide Thredd with the Client ID from the Thredd Certificate Authority Dashboard under Applications > (Your Application) > Details.

Customer Deletes an existing Client and Creates a New One

You should follow this method if you have access to the registration variables.

Use Postman to obtain a new access token.

Run the DCR Delete request in Postman.

Run the SSA request in Postman.
Run the DCR POST request

Customer Updates the Client Using the PUT Method

To update the OAuth Client, you can use the DCR PUT method. This is provided that you have access to the registration variables.

Run the DCR PUT request.

3.3.3 Identifying and Storing the registration_access_token and registration_client_uri Data

The registration_access_token and the registration_client_uri settings are returned in the response of the DCR endpoint. You must store these settings securely in order to use them again.

The following example response includes: "registration_access_token": "PKW64FAixrjhxewTH9lR26o7m6_GvbL6RKWv0x5mIM.dWPLOrdXw7yGu2R1HAWlx8dSr3Jf-thb_zNFEGSOUNg" and "registration_client_uri": "https://auth.uat.threddid.com/confidential-clients/oauth2/register/https://rp.directory.sandbox.threddid.com/openid_relying_party/b9f04639-cdeb-425b-a310-450d3d293fd4".

Copy

{
  "client_name":"Test Org 4",
  "description":"",
  "client_uri":"",
  "logo_uri":"https://example.com/logo.png",
  "policy_uri":"",
  "tos_uri":"",
  "organisation_id":"",
  "client_id":"https://rp.directory.sandbox.threddid.com/openid_relying_party/b9f04639-cdeb-425b-a310-450d3d293fd4",
  "application_type":"service",
  "application_types":[
    "service",
    "dcr"
  ],
  "redirect_uris":[
    "https://example.com/cb"
  ],
  "grant_types":[
    "client_credentials"
  ],
  "response_types":[
    "token"
  ],
  "scope":"3ds.read bulkcard.read bulkcard.write cards.encrypted cards.read cards.sensitive cards.write cvv.read cvv.write digitalchannel fraud.read fraud.write internal.read internal.write issuer.read issuer.write pin.read pin.write",
  "scopes":[
    "3ds.read",
    "bulkcard.read",
    "bulkcard.write",
    "cards.encrypted",
    "cards.read",
    "cards.sensitive",
    "cards.write",
    "cvv.read",
    "cvv.write",
    "digitalchannel",
    "fraud.read",
    "fraud.write",
    "internal.read",
    "internal.write",
    "issuer.read",
    "issuer.write",
    "pin.read",
    "pin.write"
  ],
  "audience":[
    "https://rp.directory.sandbox.threddid.com/openid_relying_party/b9f04639-cdeb-425b-a310-450d3d293fd4"
  ],
  "token_endpoint_auth_method":"private_key_jwt",
  "revocation_endpoint_auth_method":"private_key_jwt",
  "introspection_endpoint_auth_method":"private_key_jwt",
  "token_exchange":{
    "actor_claims":null
  },
  "token_endpoint_auth_signing_alg":"",
  "jwks":{
    "keys":[    
    ]
  },
  "jwks_uri":"https://keystore.directory.sandbox.threddid.com/99b2b599-8cc2-499e-b805-e3d84233ae8e/b9f04639-cdeb-425b-a310-450d3d293fd4/application.jwks",
  "request_object_signing_alg":"RS256",
  "request_object_encryption_alg":"",
  "request_object_encryption_enc":"",
  "request_uris":[
    
  ],
  "client_id_issued_at":1723556609,
  "created_at":"2024-08-13T13:43:29.619067912Z",
  "updated_at":"2024-08-13T13:43:29.619067912Z",
  "client_secret_expires_at":0,
  "sector_identifier_uri":"https://keystore.directory.sandbox.threddid.com/99b2b599-8cc2-499e-b805-e3d84233ae8e/b9f04639-cdeb-425b-a310-450d3d293fd4/redirect_uris.json",
  "userinfo_signed_response_alg":"none",
  "id_token_signed_response_alg":"ES256",
  "id_token_encrypted_response_alg":"",
  "id_token_encrypted_response_enc":"",
  "tls_client_certificate_bound_access_tokens":true,
  "tls_client_auth_subject_dn":"",
  "tls_client_auth_san_dns":"",
  "tls_client_auth_san_uri":"",
  "tls_client_auth_san_ip":"",
  "tls_client_auth_san_email":"",
  "privacy":{
    "scopes":null
  },
  "subject_type":"pairwise",
  "backchannel_token_delivery_mode":"",
  "backchannel_client_notification_endpoint":"",
  "backchannel_authentication_request_signing_alg":"",
  "backchannel_user_code_parameter":false,
  "require_pushed_authorization_requests":false,
  "authorization_signed_response_alg":"ES256",
  "authorization_encrypted_response_alg":"",
  "authorization_encrypted_response_enc":"",
  "dpop_bound_access_tokens":false,
  "authorization_details_types":null,
  "post_logout_redirect_uris":[    
  ],
  "app_url":"",
  "backchannel_logout_uri":"",
  "backchannel_logout_session_required":false,
  "client_secret":"xT4SDSlIp9J3aLMIHMtQ99Uok6onqaQJEiQ0Hp2QBXc",
  "hashed_secret":"c2dc89fd3581d6222a7a143f173a4696feee7773f4156ada52c241eea25b30990fb35f2faa42105f1e51895dd7ced75f0847659f6396fbc977cf71d73bef7a1a7f93830e871ae9fb767318b0c545ee9543dc8ae94044cfc8a9b26bcf8bad53e3ba00ef889d1d8338dfdbdedd1aed382b51a86cf5f08d21d4cbf6f23d66141c50",
  "software_id":"b9f04639-cdeb-425b-a310-450d3d293fd4",
  "software_version":"1.00",
  "software_statement":"eyJraWQiOiJzaWduZXIiLCJ0eXAiOiJKV1QiLCJhbGciOiJQUzI1NiJ9.eyJzb2Z0d2FyZV9zdGF0ZW1lbnRfcm9sZXMiOltdLCJvcmdfandrc190cmFuc3BvcnRfdXJpIjoiaHR0cHM6Ly9rZXlzdG9yZS5kaXJlY3Rvcnkuc2FuZGJveC50aHJlZGRpZC5jb20vOTliMmI1OTktOGNjMi00OTllLWI4MDUtZTNkODQyMzNhZThlL3RyYW5zcG9ydC5qd2tzIiwiYXBpX3dlYmhvb2tfdXJpcyI6W10sIm9yZ19zdGF0dXMiOiJBY3RpdmUiLCJsb2dvX3VyaSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vbG9nby5wbmciLCJyb2xlcyI6W10sImlzcyI6InRocmVkZCBzYW5kYm94IFNTQSBpc3N1ZXIiLCJvcmdfandrc190cmFuc3BvcnRfaW5hY3RpdmVfdXJpIjoiaHR0cHM6Ly9rZXlzdG9yZS5kaXJlY3Rvcnkuc2FuZGJveC50aHJlZGRpZC5jb20vOTliMmI1OTktOGNjMi00OTllLWI4MDUtZTNkODQyMzNhZThlL2luYWN0aXZlL3RyYW5zcG9ydC5qd2tzIiwiY2xpZW50X2lkIjoiaHR0cHM6Ly9ycC5kaXJlY3Rvcnkuc2FuZGJveC50aHJlZGRpZC5jb20vb3BlbmlkX3JlbHlpbmdfcGFydHkvYjlmMDQ2MzktY2RlYi00MjViLWEzMTAtNDUwZDNkMjkzZmQ0IiwiY2xpZW50X2Rlc2NyaXB0aW9uIjoiVGVzdCBPcmcgNCBpcyBhIEN1c3RvbWVyIG9mIFRocmVkZCIsIm1vZGUiOiJMaXZlIiwic29mdHdhcmVfaWQiOiJiOWYwNDYzOS1jZGViLTQyNWItYTMxMC00NTBkM2QyOTNmZDQiLCJzb2Z0d2FyZV92ZXJzaW9uIjoiMS4wMCIsIm9yZ19uYW1lIjoiVGVzdCBPcmcgNCIsInNvZnR3YXJlX2ZsYWdzIjp7fSwib3JpZ2luX3VyaXMiOltdLCJjbGllbnRfbmFtZSI6IlRlc3QgT3JnIDQiLCJpYXQiOjE3MjM1NTYzNTAsImp3a3NfdHJhbnNwb3J0X3VyaSI6Imh0dHBzOi8va2V5c3RvcmUuZGlyZWN0b3J5LnNhbmRib3gudGhyZWRkaWQuY29tLzk5YjJiNTk5LThjYzItNDk5ZS1iODA1LWUzZDg0MjMzYWU4ZS9iOWYwNDYzOS1jZGViLTQyNWItYTMxMC00NTBkM2QyOTNmZDQvdHJhbnNwb3J0Lmp3a3MiLCJvcmdhbmlzYXRpb25fdGFncyI6W10sInN1YmplY3RfdHlwZSI6InBhaXJ3aXNlIiwicmVkaXJlY3RfdXJpcyI6WyJodHRwczovL2V4YW1wbGUuY29tL2NiIl0sInNlY3Rvcl9pZGVudGlmaWVyX3VyaSI6Imh0dHBzOi8va2V5c3RvcmUuZGlyZWN0b3J5LnNhbmRib3gudGhyZWRkaWQuY29tLzk5YjJiNTk5LThjYzItNDk5ZS1iODA1LWUzZDg0MjMzYWU4ZS9iOWYwNDYzOS1jZGViLTQyNWItYTMxMC00NTBkM2QyOTNmZDQvcmVkaXJlY3RfdXJpcy5qc29uIiwib3JnX2p3a3NfaW5hY3RpdmVfdXJpIjoiaHR0cHM6Ly9rZXlzdG9yZS5kaXJlY3Rvcnkuc2FuZGJveC50aHJlZGRpZC5jb20vOTliMmI1OTktOGNjMi00OTllLWI4MDUtZTNkODQyMzNhZThlL2luYWN0aXZlL2FwcGxpY2F0aW9uLmp3a3MiLCJvcmdhbmlzYXRpb25fZmxhZ3MiOnt9LCJqd2tzX3RyYW5zcG9ydF9pbmFjdGl2ZV91cmkiOiJodHRwczovL2tleXN0b3JlLmRpcmVjdG9yeS5zYW5kYm94LnRocmVkZGlkLmNvbS85OWIyYjU5OS04Y2MyLTQ5OWUtYjgwNS1lM2Q4NDIzM2FlOGUvYjlmMDQ2MzktY2RlYi00MjViLWEzMTAtNDUwZDNkMjkzZmQ0L2luYWN0aXZlL3RyYW5zcG9ydC5qd2tzIiwiZW52aXJvbm1lbnQiOiJTYW5kYm94Iiwib3JnX2lkIjoiOTliMmI1OTktOGNjMi00OTllLWI4MDUtZTNkODQyMzNhZThlIiwib3JnX2p3a3NfdXJpIjoiaHR0cHM6Ly9rZXlzdG9yZS5kaXJlY3Rvcnkuc2FuZGJveC50aHJlZGRpZC5jb20vOTliMmI1OTktOGNjMi00OTllLWI4MDUtZTNkODQyMzNhZThlL2FwcGxpY2F0aW9uLmp3a3MiLCJqd2tzX2luYWN0aXZlX3VyaSI6Imh0dHBzOi8va2V5c3RvcmUuZGlyZWN0b3J5LnNhbmRib3gudGhyZWRkaWQuY29tLzk5YjJiNTk5LThjYzItNDk5ZS1iODA1LWUzZDg0MjMzYWU4ZS9iOWYwNDYzOS1jZGViLTQyNWItYTMxMC00NTBkM2QyOTNmZDQvaW5hY3RpdmUvYXBwbGljYXRpb24uandrcyIsIm9yZ19udW1iZXIiOiIwMDAwMDAwNCIsImp3a3NfdXJpIjoiaHR0cHM6Ly9rZXlzdG9yZS5kaXJlY3Rvcnkuc2FuZGJveC50aHJlZGRpZC5jb20vOTliMmI1OTktOGNjMi00OTllLWI4MDUtZTNkODQyMzNhZThlL2I5ZjA0NjM5LWNkZWItNDI1Yi1hMzEwLTQ1MGQzZDI5M2ZkNC9hcHBsaWNhdGlvbi5qd2tzIiwic3RhdHVzIjoiQWN0aXZlIiwib3JnYW5pc2F0aW9uX2NvbXBldGVudF9hdXRob3JpdHlfY2xhaW1zIjpbXX0.N5wPwnVFcramX7BAYOWn_1tWcLxSRNaIxst-ZK_p29he5mN1_hdFF6BoVMG0Chh-dV_FL4-luQlg7Qn3EMRCb3RWp8U7pcj0lmFSDcUyvlQpoB5hqrXgjPEOkIC7uqJuTDjwakj0NFtJDtK_l_FVp-PA2ZsDJanwCxsnxxMxVFlxFPwCYk8jBTNE84zx092a4-Tj4VfE4e5S5HA7if8sR7PiXvAMWs1jBrUQ9enWacfu_Xno_-kywtrkAeR4fi-MGNeA4IkbYbh8LyhMjg3XXun87BoL8-b_An5fX5y-XS8VnENg3NFU3D8soQ05OKlXnIDT2Dp7v1lFlNYrV1jO9w",
  "dynamically_registered":true,
  "registration_access_token":"PKW64FAixrjhxewTH9lR26o7m6_GvbL6RKWv0x5mIM.dWPLOrdXw7yGu2R1HAWlx8dSr3Jf-thb_zNFEGSOUNg",
  "registration_client_uri":"https://auth.uat.threddid.com/confidential-clients/oauth2/register/https://rp.directory.sandbox.threddid.com/openid_relying_party/b9f04639-cdeb-425b-a310-450d3d293fd4",
  "registration_access_token_expires_in":0
}