You are here: Home > Get Support > Documentation > Developer Documentation > RPKI Management API

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:

  1. Log into the LIR Portal with a user account that has administrator credentials
  2. Click the API Access Keys link in the Tools section
  3. Create a key for the Resource Certification (RPKI) API

Please note that 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:

Get a list of your certified resources

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

$ curl https://my.ripe.net/api/rpki/resources?key=[your-api-access-key]
{
"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.
 
$ curl https://my.ripe.net/api/rpki/announcements?key=[your-api-access-key]
[
{
"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.

$ curl https://my.ripe.net/api/rpki/roas?key=[your-api-access-key]
[
{
"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. The format of the JSON is as follows:

{
 "added":[
    {
       "asn":"AS2121",
       "prefix":"193.0.24.0/21",
       "maximalLength":"21"
    }
 ],
 "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":[
"user1 _at_ example _dot_ net","user2 _at_ example _dot_ net"
],
"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]

Supressing 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 supress 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'"}