# Appendix K- API Keys

API keys are a way to authenticate updates in the RIPE database. They are associated with a user's RIPE NCC Access account, and are intended to help users script (automate) updates to the RIPE Database.

# Introduction

API keys are a 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. If you only make updates using the web interface, then you don't need API keys!

Before authenticating with an API key, your RIPE NCC Access account must already be associated with the object mntner using an "auth:" SSO attribute.

To start using API keys, go to the Web query page, login to RIPE NCC Access, and go to the API keys page on the left-hand menu. https://apps.db.ripe.net/db-web-ui/api-keys

# Create a New Database Key

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 Authorization 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

To authenticate using an API key, you must first associate your RIPE NCC Access account with a maintainer using an auth: SSO attribute. Then you can authenticate queries and updates as your 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.

For example:

$ curl -v --header "Accept: application/xml" \
 --header "Authorization: Basic NkhEVORLSFFETVBHVUE5VFpJQjVSRFVCOlc2R2FFdDJTa1Ry
Rk84eGgyRXFGVTRQaA==" \
 https://rest.db.ripe.net/ripe/mntner/shryane-mnt?unfiltered

# Authenticated 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.

For example:

$ curl -v \
  --header "Authorization: Basic NkhEVORLSFFETVBHVUE5VFpJQjVSRFVCOlc2R2FFdDJTa1Ry
Rk84eGgyRXFGVTRQaA==" \
 -X PUT -d @output \
 --header "Content-type: application/xml" \
 https://rest.db.ripe.net/ripe/person/ES7554-RIPE

The 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.

# JSON Example

By default, the Whois REST API uses XML format. However you can also use API keys with JSON formatted objects. Either use the ".json" filename extension at the end of the URL path, and/or specify the "application/json" content type.

First query for an object to be updated with a JSON response, for example :

$ curl -v --header "Accept: application/json" \
 -o output \
 https://rest.db.ripe.net/ripe/person/ES7554-RIPE.json?unfiltered

Then edit the "output" file and make a change to the object.

Then make the update in the database specifying JSON formatted data, for example :

$ curl -v \
  --header "Authorization: Basic NkhEVORLSFFETVBHVUE5VFpJQjVSRFVCOlc2R2FFdDJTa1Ry
Rk84eGgyRXFGVTRQaA==" \
 -X PUT -d @output \
 --header "Content-type: application/json" \
 https://rest.db.ripe.net/ripe/person/ES7554-RIPE.json