Creating and managing API keys

Introduction

It is possible to authenticate with the REST API using API keys. API keys let you access restricted data and perform certain actions without signing in to the RIPE NCC Access single sign-on system.

Each API key allows a set of actions to be performed in your name. For example, a single key may allow the creation of a new user-defined measurement and would also allow hidden information about your probe to be viewed.

The two main reasons for using API keys are to:

• Make it simpler to write scripts that use RIPE Atlas data
• Allow you to easily and securely share data with other people

Creating keys

New keys can be created using the "My API Keys" card on the dashboard (opens new window). (Click on the plus symbol in the title bar)

API create new button

You will be presented with the following choices:

• Label: This is a free-text string that you can use to help organise your keys
• Valid from: Keys won't work until this time. If you leave this blank, they will be effective immediately
• Valid to: Keys will stop working at this time. If you leave this blank, your key will never automatically expire
• Enabled: Keys will not work unless this is on

You should add one or more grants to your key to assign particular permissions. Each grant takes the following options:

• Permission: This is the specific type of permission you want to assign. A permission will generally correspond to one function and one API URL prefix
• Target: This limits the grant to provide access either to a specific object that you own, such as an individual probe or user-defined measurement. With some permissions, you can provide access to all objects of the relevant type. Note: In some cases, the target option is not applicable

Using keys

For instructions on using API keys in your scripts or your shared URLs, refer to the API Keys section in the REST API manual.

Managing keys

Once a key is created, its properties can be viewed and edited by clicking on the menu on the right of each row.

In the editing screen, it is possible to disable a key, which means you can retract access whenever you like. You can also regenerate the UUID.

API action menu

Supported permissions

Permissions will gradually be introduced to cover more RIPE Atlas functionality. In particular, suggestions from the community will have an impact on which new permissions are created. Please send suggestions to atlas@ripe.net.

The available permissions are shown in the "Permission" dropdown in the create and edit screens.