RPKI Management API

Introduction

The RPKI Management API allows you to manage your Certificate Authority and ROAs systematically. Everything that you can do within the management interface in the LIR Portal is possible in the API, ranging from requesting which BGP announcements you do with your certified address space, to creating ROAs and setting up alerts. The API accepts HTTP POST messages with JSON in the payload.

Creating an API Access Key

Because the RPKI is private for your LIR, it is only accessible through the API after creating an access key. In order to this, please follow these steps:

Log into the LIR Portal with a user account that has administrator credentials
Click the API Keys link in the LIR Portal
Create a key for the Resource Certification (RPKI) API

Please note that the value of the key is displayed only once, when it is created, and the hashed value is stored in the database. You are responsible for maintaining your keys. You can create as many keys as you like and revoke unused keys as needed.

Usage

The API is available on both the production and pilot systems. This means you can test your configuration on the pilot first without affecting prodution data. These are the base URLs for the different servers:

Pilot system: https://localcert.ripe.net/api/rpki
Production system: https://my.ripe.net/api/rpki

Appending the key:

They key can be passed to the request as a URL parameter or as a request header value. We strongly recommend using the header to pass the API Key, so that the key is not stored in any server logs.

--header 'ncc-api-authorization: <api-key>' 
or 
?key=<api-key>

Get a list of your certified resources

This is a GET call that results in a list of all resources on your certificate

https://my.ripe.net/api/rpki/resources

{
 "resources": [
 "84.205.64.0/19",
 "93.175.144.0/20",
 "193.30.30.0/23",
 "2001:67c:e0::/48",
 "2001:67c:2e8::/48",
 "2001:67c:2888::/47",
 "2001:67c:2900::/43",
 "2001:67c:2d7c::/48",
 "2001:7fb::/32",
 "2001:7fd::/32"
 ]
}

Get all BGP announcements

This is a GET call that results in a list of all BGP announcements that are done with your certified address space, according to the RIPE NCC RIS Route Collectors.

Description:

asn: The origin AS
prefix: The announced prefix
visibility: How many peers see this announcement, according to the route collectors
currentState: The current RPKI Validity state of this announcement
suppressed: Should email alerts be sent if this announcements is INVALID or UNKNOWN

This call is useful to see which of your BGP Announcements are VALID, INVALID and UNKNOWN, so you can take action when you are either being hijacked, or your ROA configuration needs attention. Please keep in mind that RIS Route Collector data is updated every 8 hours, so recent changes might not be visible immediately.

$ https://my.ripe.net/api/rpki/announcements

[
 {
 "asn": "AS12654",
 "prefix": "2001:7fb:fe0f::/48",
 "visibility": 90,
 "currentState": "VALID",
 "suppressed": false
 },
 {
 "asn": "AS12654",
 "prefix": "84.205.71.0/24",
 "visibility": 98,
 "currentState": "VALID",
 "suppressed": false
 },
 {
 "asn": "AS12654",
 "prefix": "2001:7fb:ff03::/48",
 "visibility": 85,
 "currentState": "UNKNOWN",
 "suppressed": true
 }
]

Get all ROAs

This is a GET call that results in a list of all ROAs that you have created.

$ https://my.ripe.net/api/rpki/roas

[
 {
 "asn": "AS12654",
 "prefix": "84.205.76.0/24",
 "maximalLength": 24,
 "_numberOfValidsCaused": 1,
 "_numberOfInvalidsCaused": 0
 },
 {
 "asn": "AS12654",
 "prefix": "2001:7fb:ff02::/48",
 "maximalLength": 48,
 "_numberOfValidsCaused": 1,
 "_numberOfInvalidsCaused": 0
 }
]

Description:

asn: The origin AS you authorise
prefix: The prefix you authorise
maximalLength: The maximum length you authorise
_numberOfValidsCaused: The number of valid BGP announcements this ROA causes
_numberOfInvalidsCaused: The number of invalid BGP announcements this ROA causes

Adding and deleting ROAs

When you want to update your ROAs, POST the contents of a file with the ROAs you would like to add and/or delete. Multiple ROAs are allowed in the same call. The format of the JSON is as follows:

{
"added": [
{
"asn": "AS12654",
"prefix": "2001:7fb:fd03::/48",
"maximalLength": "48"
},
{
"asn": "AS12654",
"prefix": "2001:7fb:ff03::/48",
"maximalLength": "48"
}
],
"deleted": []
}

In this example, the file is saved as roas.json. Add the -v flag if you would like verbose output.

$ curl -H "Content-Type: application/json" --data @roa.json
  https://my.ripe.net/api/rpki/roas/publish?key=[your-api-access-key]

BGP announcements affected by a ROA

It can be useful to get specific information on how your BGP announcements are affected by a ROA. This can be a ROA that you have already created, or one that doesn't exist (yet). The latter is useful for finding out what the effect on your BGP announcements would be, if you would create a certain ROA. Keep in mind that when determining the validity state of a BGP announcement, this query takes all your existing ROAs into account. We will only warn you about any INVALID BGP announcements if no other existing ROA authorises it.

$ curl -H "Content-Type: application/json" -d
  '{"asn":"AS65411","prefix":"193.0.24.0/21","maximalLength":21}'
  https://my.ripe.net/api/rpki/announcements/affected?key=[your-api-access-key]

[
 {
 "asn":"AS2121",
 "prefix":"193.0.24.0/21",
 "visibility":108,
 "currentState":"INVALID_ASN",
 "suppressed":false
 }
]

In this case, the result is that one BGP announcement – 193.0.24.0/21 from AS2121 – will become INVALID because it would be originated from unauthorised ASN.

Alerts

When you want to subscribe to email alerts, POST the contents of a file with the email addresses and the type of alerts you want to receive:

{
 "emails":[
    "[email protected]","[email protected]"
 ],
 "routeValidityStates":[
    "INVALID_ASN","INVALID_LENGTH","UNKNOWN"
 ]
}

In this example, the file is saved as alerts.json. Add the -v flag if you would like verbose output.

$ curl -H "Content-Type: application/json" --data @alerts.json
  https://my.ripe.net/api/rpki/alerts?key=[your=api-access-key]

Suppressing alerts for a BGP announcement

If one of your BGP announcements has the status UNKNOWN or INVALID and you do not wish to receive an email alert about it, then you can suppress it:

$ curl -H "Content-Type: application/json" -d '[{"asn":"AS2121","prefix":"193.0.24.0/21"}]'
  https://my.ripe.net/api/rpki/alerts/suppress?key=[your-api-access-key]

You can re-enable alerts with unsuppress:

$ curl -H "Content-Type: application/json" -d '[{"asn":"AS2121","prefix":"193.0.24.0/21"}]'
  https://my.ripe.net/api/rpki/alerts/unsuppress?key=[your-api-access-key]

Both commands will not return any data, but respond with status code "HTTP/1.1 200 OK" if successful.

Error codes

The API will return detailed messages if you make a mistake. In these examples, the '-i' flag is added to curl to display the associated HTTP status codes.

Incorrect API Access Key

An incorrect API Access Key will result in a "401 Unauthorized" error.

$ curl https://my.ripe.net/api/rpki/roas?key=[false-api-access-key]

HTTP/1.1 401 Unauthorized
Date: Mon, 09 Feb 2015 12:59:49 GMT
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: *
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 1728000
X-Response-Time: 39
Content-Length: 0
Connection: close
Content-Type: text/plain; charset=UTF-8

Creating an invalid ROA

If you try to create a ROA for a prefix that you are not the holder of, you will get a "403 Forbidden" error, with detailed information in the body.

$ curl -H "Content-Type: application/json" --data @roa.json
  https://my.ripe.net/api/rpki/roas/publish?key=[your=api-access-key]

HTTP/1.1 403 Forbidden
Date: Mon, 09 Feb 2015 12:59:49 GMT
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: *
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 1728000
X-Response-Time: 39
Content-Length: 0
Connection: close
Content-Type: text/plain; charset=UTF-8
{"error":"You are not a holder of the prefix 194.0.24.0/21"}

Malformed JSON

If you make a syntax error in your JSON request, or try to post a ROA containing a non-existing prefix, you will get a "400 Bad Request" error.

$ curl -H "Content-Type: application/json" --data @roa.json
  https://my.ripe.net/api/rpki/roas/publish?key=[your=api-access-key]

HTTP/1.1 400 Bad Request
Date: Mon, 09 Feb 2015 12:59:49 GMT
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: *
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 1728000
X-Response-Time: 39
Content-Length: 0
Connection: close
Content-Type: text/plain; charset=UTF-8
{"error":"Bad request for '/api/rpki/roas/publish' with error 'Invalid Json'"}