Resource Request API

Currently we support the following resource requests through the API:

Autonomous System (AS) Number Assignment
IPv4 First Allocation
IPv6 First Allocation
IPv6 Provider Independent (PI) Assignment

The Request Resource API accepts HTTP POST messages with JSON in the payload specifying the resource request type and the information required by the RIPE NCC to process and accept the request.

Creating an API Access Key

To use this API, you must create an application specific API 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 Access Keys link in the Tools section
Create a key for the Resource Request 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 Resource Request JSON payload for all requests share the same structure. The first part is generic and only the requestType is different per request type.

{
"requestType": "REQUEST_TYPE",
"contactPreferred": true,
"contactPersonName": "Tom Smith",
"contactPersonEmail": "tom.smith@example.org",
"contactPhoneNumber": "+31634567890",
"additionalEmailDetail": "additional-1@example.com, additional-2@example.com",
"requestContent": {
Request Type specific JSON
}
}

The requestType, contactPreferred, contactPersonName and contactPersonEmail are required. As is the requestContent which is different for each request type. You specify that you would like to be contacted by specifying:

"contactPreferred": true

If you don't want to be contacted you can omit this property. The additionalEmailDetail property is also optional, if specified it contains the additional email addresses - comma separated - that will also receive a notification containing a summary of the request.

Using an ASN request as an example, a minimum generic part of the JSON could be:

{
"requestType": "AsnAssignment",
"contactPreferred": false,
"contactPersonName": "Tom Smith",
"contactPersonEmail": "tom.smith@example.org",
"requestContent": {
Request Type specific JSON
}
}

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>

In the following sections we will explain the specific requestContent parts of the JSON, depending on the request type.

Autonomous System (AS) Number Assignment

For requesting an AS Number assignment, the following endpoint is available:

https://my.ripe.net/api/external/v1/request/asn/assignment

The payload of the HTTP POST message for AS Number assignments:

{
"requestType": "AsnAssignment",
"contactPreferred": false,
"contactPersonName": "Tom Smith",
"contactPersonEmail": "tom.smith@example.org",
"requestContent": {
"asnName": "RIPE-NCC-AS",
"adminc": "my-admin-c",
"techc": "my-tech-c",
"mntBy": "my-mnt-by",
"mntRoutes": "my-mnt-routes",
"country": "NL",
"currentAsns": ["AS111", "AS222"],
"peeringPartners": [
{"asn": "AS333", "email": "partner-1@domain.com", "import": "from AS333 accept ANY", "export": "to AS333 announce ASNEW"},
{"asn": "AS444", "email": "partner-2@domain.com", "advancedRoutingPolicy": "from AS444 accept ANY"}
],
"addressPrefix": "22",
"onBehalfOfCustomer": true,
"customer": {
"organisation": "ORG-customer-RIPE",
"organisationName": "customer-org-name",
"adminc": "customer-admin-c",
"techc": "customer-tech-c",
"mntBy": "customer-mnt-by",
"mntRoutes": "customer-mnt-routes",
"website": "http://www.name.org"
},
"attachments": [
{
"fileName": "contract.pdf",
"content": "ZHVtbXkgY29udHJhY3Q="
},
{
"fileName": "agreement.pdf",
"content": "ZHVtbXkgY29udHJhY3Q="
}
]
}
}

Required fields are asnName, adminc, techc, mntBy, mntRoutes, country, currentAsns (may be an empty array), peeringPartners, addressPrefix and onBehalfOfCustomer.

If you don't have current AS Numbers then the currentAsns can be an empty array (e.g. []).

It is required to have a minimum of two peering partners and both ASN and email must be specified. You can either specify the import and export rules, or you can omit them and specify a advancedRoutingPolicy. Lastly, each peering partner must have a unique ASN.

If you make the request on behalf of a customer then the "customer" section is required. If you make the request for your own infrastructure the customer element can be omitted. Within the customer element the organisation, organisationName and website are required. The RIPE Database fields adminc, techc, mntBy and mntRoutes are optional within the customer element.

If you do make the request on behalf of a customer then you are required to submit at least one attachement with both fileName and content required. The content field is the actual contents of the file Base64 encoded.

If you don't make the request on behalf of a customer then this is an example of the minimum JSON required:

IPv4 First Allocation

For requesting an IPv4 First Allocation, the following endpoint is available:

https://my.ripe.net/api/external/v1/request/ipv4/allocation

The payload of the HTTP POST message for IPv4 First Allocations is:

{
"requestType": "Ipv4FirstAllocation",
"contactPreferred": false,
"contactPersonName": "Tom Smith",
"contactPersonEmail": "tom.smith@example.org",
"requestContent": {
"prefixLength": 22,
"adminc": "my-admin-c",
"techc": "my-tech-c",
"mntRoutes": "my-mnt-routes",
"mntLower": "my-mnt-lower",
"country": "NL"
}
}

All of the fields in the payload are required and validated against the RIPE Database. The prefixLength is /22 for the first allocation and the request is not valid if the LIR has already received their last /22 allocation.

IPv6 First Allocation

For requesting an IPv6 First Allocation, the following endpoint is available:

https://my.ripe.net/api/external/v1/request/ipv6/allocation

The payload of the HTTP POST message for IPv6 First Allocations is:

{
"requestType": "Ipv6FirstAllocation",
"contactPreferred": false,
"contactPersonName": "Tom Smith",
"contactPersonEmail": "tom.smith@example.org",
"requestContent": {
"prefixLength": 32,
"adminc": "my-admin-c",
"techc": "my-tech-c",
"mntRoutes": "my-mnt-routes",
"mntLower": "my-mnt-lower",
"country": "NL"
}
}

All of the fields in the payload are required and validated against the RIPE Database. The recommended prefixLength for an IPv6 First Allocation is /32. For allocations larger than a /29, it is required to provide documentation that justifies the request, such as the number of existing users or the extent of the organisation's infrastructure. The RIPE NCC will contact the requesting LIR as soon as possible to discuss the details.

IPv6 Provider Independent (PI) Assignment

For requesting IPv6 PI Assignments, the following endpoint is available:

https://my.ripe.net/api/external/v1/request/ipv6/pi-assignment

The payload of the HTTP POST message for IPv6 PI Assignments is:

{
"requestType": "Ipv6PIAssignment",
"contactPreferred": false,
"contactPersonName": "Tom Smith",
"contactPersonEmail": "tom.smith@example.org",
"requestContent": {
"prefixLength": 32,
"adminc": "my-admin-c",
"techc": "my-tech-c",
"mntBy": "my-mnt-by",
"country": "NL",
"providerIndependentRationale": ["I have routing reasons"],
"additionalProviderIndependentRationale": "Really urgent routing reasons",
"addressingPlans": [
{
"prefixLength": 39,
"period": "3 Months",
"purpose": "purpose1"
},
{
"prefixLength": 39,
"period": "1 Year",
"purpose": "purpose2"
},
{
"prefixLength": 39,
"period": "2 Years",
"purpose": "purpose3"
}
],
"onBehalfOfCustomer": true,
"customerOrganisation": "ORG-customer-RIPE",
"customerOrganisationName": "customer-org-name",
"customerWebsite": "http://www.name.org",
"customerMntBy": "customer-mnt-by",
"customerAdminc": "customer-admin-c",
"customerTechc": "customer-tech-c",
"attachments": [
{
"fileName": "contract.pdf",
"content": "ZHVtbXkgY29udHJhY3Q="
},
{
"fileName": "customer",
"content": "ZHVtbXkgY29udHJhY3Q="
}
],
"additionalComments": "Some details about services to be provided using the requested space"
}
}

Required fields are requestType (with the value Ipv6PIAssignment), contactPersonName, contactPersonEmail and contactPreferred in the main section. In the requestContent section, the fields prefixLength, adminc, techc, mntBy, country, onBehalfOfCustomer are required. In addition, the LIR is required to add at least addressingPlan to the addressingPlans array. If the request is made on behalf of a customer then the following fields are required: customerOrganisation (the ORG-ID of the customers organisation), customerOrganisationName and customerWebsite and at least one attachment. If the request is made on behalf of a customer then customerMntBy, customerAdminc and customerTechc are optional. Required field additionalComments should contain some details about services to be provided using the requested space.

If you do make the request on behalf of a customer then you are required to submit at least one attachment (e.g. the End User Assignment Agreement and preferably the customer's company registration papers) with both fileName and content required. The content field is the actual contents of the file Base64 encoded. We provide a model agreement that you can use for this purpose.

Optional fields are additionalProviderIndependentRationale. The providerIndependentRationale is an array of rationale that will be reviewed by the RIPE NCC.

If you don't make the request on behalf of the customer, then this is an example of the minimum JSON required for an IPv6 PI Assignment:

{
"requestType": "Ipv6PIAssignment",
"contactPreferred": false,
"contactPersonName": "Tom Smith",
"contactPersonEmail": "Tom.Smith@example.org",
"requestContent": {
"prefixLength": 32,
"adminc": "my-admin-c",
"techc": "my-tech-c",
"mntBy": "my-mnt-by",
"country": "NL",
"providerIndependentRationale": ["I want to be provider independant"],
"addressingPlans": [
{
"prefixLength": 32,
"period": "1 Year",
"purpose": "IP range to migrate away from Provider"
}
],
"onBehalfOfCustomer": false
}
}

Validation in General

All of the fields are validated both on presence (if mandatory) or on correctness (are they present in the RIPE Database, for example). If there are omissions in the JSON and/or invalid content then the response will have a status of 400 (Bad Request) and list all the errors in the request payload. The following response indicates that in the main 'obj' (e.g. the root of the JSON) the required regId was not provided.

{
"errors": [
{
"path": "obj",
"msg": "The regId is required"
}
]
}

If all of the required fields are present then the error message will report on invalid content. If, for example, the adminc, mntBy are not known and a asnName 'as-123-!' is provided, the response would be:

{
"errors": [
{
"path": "obj",
"msg": "invalid-role: admin-c object does not exist in the RIPE database"
},
{
"path": "obj",
"msg": "invalid-mnt: mnt-by object does not exist in the RIPE database"
},
{
"path": "obj",
"msg": "'as-123-!' is an invalid as-name"
}
]
}