The API key is UUID which is normally used to authorize a user. The API key is not URL safe (that is, passing a key to the API is not safe) and anyone with this API key can access the system.
Whereas the API token is an encoded, complex string that contains user data, which is URL safe and is the Internet standard for API’s. Moreover, it can be configured with an expiry time, which ensures more safety to the system. It's common practice to use an API token rather than an API key.
For this reason, CKAN, the underlying system of the IATI Registry, recommends using API tokens for authentication. Tokens are encrypted keys that can be generated manually from the UI or using the api_token_create() API function. A user can create as many tokens as needed, and revoke tokens at any time. When a new token is generated this will not be visible after its creation, thus nobody will be able to gain access to the token.
More information on API tokens vs. API keys can be found here.
We propose to improve the security of the Registry API by encouraging the Registry API users to start using the API tokens for authentication since they are considered the standard practice for HTTP-based APIs. The API token generation is already part of the IATI Registry UI, as well as the API, thus the API users can start using this feature right away.
The Registry UI will go through a change whereby the API key generation and key display will be removed and users will be required to navigate to the existing API token tab to generate their tokens.
The Registry API authentication will still support the legacy API keys, but its use is discouraged.
What change is required by the Registry API users?
Registry API users, such as data access tools, who currently do not use endpoints that require Authentication will not be affected and no change is needed at their end.
Registry API users who use endpoints that require Authentication and currently use an API Key are encouraged to start using the api_token_create() API function to generate a token instead. No change will be required to the authorisation header of your requests, this will stay ('Authorization', 'Your API Token'). Further details on the API authentication can be found in the CKAN user guide.
Registry API users who require IATI publishers to link their IATI Registry account to a publishing tool via an API key will need to take in consideration 3 scenarios.
- Existing publishers who currently use an API key to link the systems do not need to change their API key and will not be affected.
- Existing publishers who currently use an API key to link the systems and need to update the API key for any reason (e.g. they deleted the key by accident) will need to be able to input an API token in the tool.
- New publishers who use a third party publishing tool will need to be able to use an API token to link the tool to their IATI Registry.
No change will be required to the authorisation header of your requests, this will stay ('Authorization', 'Your API Token'). Further details on the API authentication can be found in the CKAN user guide.
Post your feedback by 22 October
Please review the above mentioned changes and share any feedback by responding to this thread by Friday, 22 October.
If you require clarification or have questions please contact the IATI Technical Team at email@example.com or tag us in the thread below.
The IATI Technical Team will directly contact each publishing tool provider and publishers with bespoke in-house publishing systems to inform them about the changes.
After understanding the timeframe required from tool providers and publishers to implement the changes at their end, and after reviewing the feedback received from the IATI community we will begin work on creating a timeframe for the IATI Registry changes. The timeframe will be shared in this thread.