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.
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.
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 to be able to log in to the WMDA Portal using MFA (see MFA user guide).
Responsibilities:
Your organisation should designate one or more credential managers responsible for managing API credentials.
Only users with the credential manager role assigned by the WMDA team can access the Manage API Credentials page.
WMDA cannot assign this role without confirmation from your organisation.
As a credential manager, you can use the Manage API Credentials page to:
2. Provide client secret name and expiration date (one year maximum) for this secret:
The maximum expiration date for a client secret is one year to comply with the WMDA security policies.
We advise including your name in the "client secret name" field (e.g., "Secret by John Doe") so the WMDA team can contact you if troubleshooting or follow-up is needed. |
3. Click on "Create".
4. Copy the client secret that appears:
When you create a new secret, copy and store it securely. After you refresh or return to this page, the full secret will no longer be visible - only the first three characters (hint) will remain. If you don't copy the newly created secret, you lose it, and you'll need to generate a new secret.
|
Once a new client secret is in use, the old one should be removed to prevent unnecessary expiration reminders and confusion.
Click on the delete icon next to the secret you would like to delete and confirm your action:
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:
This recommended workflow mirrors real-world operational practice and avoids outages.
Do Not
Do not create client secrets with a short expiration date unless required for specific testing purposes. We recommend using the maximum expiration of 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.
To authenticate with the WMDA APIs, a bearer token must be requested from the WMDA. For details on how the client ID and client secret are used to retrieve bearer tokens and authenticate future requests to the WMDA API, see API authentication. |
WMDA team creates applications for members that implement WMDA APIs. To securely connect to these applications, the IT team provides API credentials, which consist of:
API credentials are used exclusively for machine-to-machine authentication and are not intended for user login.
Client ID
Client secret
Client ID stays the same permanently. It does not expire and does not need to be replaced. Client secret expires after a set period. When the client secret expires, API connections will stop working until a new secret is created and updated in your systems. To avoid interruptions, always rotate the secret before it expires. |
The Manage API Credentials page lists the application registrations (referred to as applications in this guide) created by the WMDA 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 team; members cannot create or modify them.
Examples of applications you may see on the Manage API Credentials page:
Partner-NL-OrganisationName-SMC
PartnerAlternative-NL-OrganisationName-SMC (sandbox only)
Depending on the API permissions assigned to your application, it may have access to the following WMDA resources:
PartnerAlternative is a "dummy" application for implementers to test their Match-Connect API integration internally. It works only in the Match-Connect sandbox and is provided upon request. |
The credential managers will automatically receive email notifications from WMDA when a client secret is approaching expiration.
Notifications are sent at the following intervals: