the page is not not public yet

Who is it for?

This guide is intended for technical contacts at WMDA member organisations who manage API integrations and credentials. In this guide, we refer to these contacts as Credential Managers - the designated technical users responsible for managing API credentials.

Quick summary

• What credential managers can do?: View, create, and delete client secrets for your applications.
• What WMDA does vs & what members do: WMDA creates and manages the applications and provides each application with a permanent client ID and a client secret; members manage their own client secrets associated with these applications using the dedicated portal page.
• Why secret rotation matters: Client secrets expire periodically. Rotating them on time ensures uninterrupted API access and maintains security.

1. Manage API Credentials

You can manage API credentials using the Manage API Credentials page, where you can view, create, and delete client secrets.

API credentials consist of a client ID and a client secret. This portal allows you to manage the client secrets associated with each application. See 2. About API Credentials & 3. Applications on the Manage API Credentials Page below for more details.

1.1 Access to the Manage API Credentials Page

1. Visit the Manage API Credentials page https://portal.wmda.info/manage-api-credentials.
   1. You must login to the WMDA Portal using MFA (MFA user guide).
   2. You must have the credential manager role assigned by the WMDA team.

Image Modified

Who can be assigned the credential manager role?

• Any user within your organisation who has access to the WMDA Portal can be assigned this role.

• This user does not need access to any other WMDA Portal pages (e.g. Search & Match or Data Manager). They only need user need to be able to log in to the WMDA Portal using MFA (see MFA user guide).

• The credential manager role is assigned per application. We recommend having at least 2 users per application to ensure this sensitive responsibility does not become a bottleneck and that a backup user is available.
• Practical guidance: Assign this role to someone who can responsibly manage API credentials and coordinate with your technical team. This could be someone who is part of the technical team or closely involved in API implementation.

...

• View the applications and their client IDs provided by the WMDA team.
• Create new client secrets for these applications.
• See expiration date for each client secret.
• Delete client secrets that are no longer needed.

Image Modified

1.2 Create a Client Secret

1. Visit the Manage API Credentials page https://portal.wmda.info/manage-api-credentials and click on the "Create new secret" button and the pop-up will appear:

Image Modified

2. Provide client secret name and expiration date (1 one year maximum) for this secret:

Image Modified

 The The maximum expiration date for a client secret is one year to comply with the WMDA security policies.

...

4. Copy the client secret that appears:

Image Modified

...

1.3 Delete a Client Secret

1. Click on the delete icon next to the secret you would like to delete and confirm your action:

Image Modified

1.4 Expiring Client Secrets

To inform credential managers about secrets that are about to expire, email notifications are sent by WMDA. See 4. Email Notifications About Expiring Client Secrets below for more details.

Client secret that is about to expire (in less than one month) is marked with an icon   next to the expiration date on the Manage API Credentials page:

Image Modified

1.5 Recommended Rotation Workflow

1. Create new client secret.
2. Update it in your system.
3. Confirm connectivity.
4. Delete old client secret.

...

• Do not create client secrets with a short expiration date unless required for specific testing purposes. We recommend using the maximum expiration of 1 one year to minimise rotation work.

• Do not share client secrets with anyone outside your organisation. Treat them as confidential credentials.

• Do not use expired secrets - they will break API connections. Always create a new secret before the old one expires.

• Do not delete secrets currently in use without first updating systems that rely on them. Deleting an active secret will immediately stop API access.

2. About API Credentials

WMDA IT team creates applications for member organisations members that implement WMDA APIs. To securely connect to these applications, the IT team provides API credentials, which consist of:

...

• A confidential credential linked to a specific client ID.
• Acts like a temporary password for machine-to-machine authentication.
• Required when requesting a bearer token to connect to the WMDA APIs.
• Expires after a set period. A replacement must be created and used.
• Can be managed by your organisation's credential managers on the Manage API Credentials page.

...

The Manage API Credentials page lists the application registrations (referred to as applications in this guide) created by the WMDA IT team for your organisation. Each application represents access to one or more APIs.

Each application is associated with a client ID and client secrets, which can be managed by credential managers using the WMDA Portal.

These applications are created and managed by the WMDA IT team; member organisations cannot WMDA team; members cannot create or modify them.

Examples of applications you may see on the Manage API Credentials page:

...

Each application has its own client ID and client secret. Visibility depends on your user role and the API permissions assigned to your application by the WMDA team.

4. Email Notifications About Expiring Client Secrets (Coming Soon)

This feature is not yet available, and no emails are currently sent regarding expiring client secrets. More details will be provided once the feature is live.

The credential managers for your organisation managers will automatically receive email notifications from WMDA when a client secret is approaching expiration.

...