API keys are a new way to authenticate updates in the RIPE Database. They are associated with a user’s RIPE NCC Access account, and are intended to help you script (automate) updates to the RIPE Database.
We are introducing API keys as an easy to use alternative to MD5 hashed passwords, which we plan to deprecate later this year. For now, API keys can only be used in the RIPE database, but we intend to offer them in other RIPE NCC services in the future.
For anyone reading this who only makes updates using the web interface - you don’t need API keys! For everyone else, in this article, I'm going to show you the new API keys feature of the RIPE database.
To start using API keys, the first step is to log in to the LIR Portal and go to the API keys page in the left-hand menu.
Video demo
Create a new database key
Here are all the steps you need to follow:
- On the API Keys page, click on "Create a new Database key".
- Enter a key name (required) : a short description of how the key will be used.
- Enter an expiration date (required) : when does the API key stop working. Keys are time-limited for security reasons and are valid up to a year in the future.
- Enter a maintainer (optional) : if you have added your RIPE NCC Access account to more than one maintainer, you can restrict the API key to only work with one specified maintainer.
- Then click on "Create a key".
When the key is created you'll see a popup:
The API key is composed of two parts. You can either use it combined in a single HTTP Authorisation header, or separately as a username and password using your HTTP client.
Make sure to copy down either the combined header value or the username and password. The password will only be shown to you once. The username will be used subsequently as the key id.
List Database keys
After closing the popup, the new key appears in a list, including:
- Name (the text you entered describing the key)
- Key ID (the generated username part of the key)
- Last Used (the last time the key was used to successfully authenticate an update)
- Expiration date (the date on which the key expires and can no longer be used)
- Details (any other attributes such as the maintainer if entered)
Authenticated queries using an API key
My RIPE NCC Access account is already associated with the maintainer using an auth: SSO attribute.
I can now authenticate queries and updates as my RIPE NCC account using the newly created API key.
You need to authenticate a database query if you want to update a maintainer, so you can read the entire object including auth: attributes unfiltered. The entire mntner object is returned, including all auth: attributes and no "Filtered" comment.
$ curl -v --header "Accept: application/xml" \
--header "Authorization: Basic NkhEVORLSFFETVBHVUE5VFpJQjVSRFVCOlc2R2FFdDJTa1Ry
Rk84eGgyRXFGVTRQaА==" \
https://rest.db.ripe.net/ripe/mntner/shryane-mnt?unfilteredAuthenticated updates using an API key
We will now update a person object that is used as a tech-c: attribute by the maintainer.
- First query for the unfiltered person object. You don’t need to authenticate this step.
$ curl -o output https://rest.db.ripe.net/ripe/person/ES7554-RIPE?unfiltered- Then edit the "output" file and make a change to the person object.
- Then make the update in the database.
$ curl -v \
--header "Authorization: Basic NkhEVORLSFFETVBHVUE5VFpJQjVSRFVCOlc2R2FFdDJTa1Ry
Rk84eGgyRXFGVTRQaА==" \
-X PUT -d @output \
--header "Content-type: application/xml" \
https://rest.db.ripe.net/ripe/person/ES7554-RIPEThe person object is updated successfully if the response is 200 OK.
Revoking an API key
If you suspect that an API key has been compromised - e.g. if anyone else could know what it is - then it’s safest to revoke the key and create a new one.
To do this, find the API key on the page and click on the “Revoke” button
As soon as you revoke a key it cannot be used to authenticate queries or updates in the RIPE database.
Conclusion
We hope users will find this new way to authenticate queries and updates in the RIPE database useful! That said, if any of the above is unclear, or you have any other questions about this feature, you can reach us at ripe-dbm@ripe.net.
Comments 0