Skip to main content

Getting started

Welcome to Nameshield Developer APIs.

The base URL for the production environment is :

https://api.nameshield.net/

We provide a separate OTE environment for testing.
Integrate with the OTE environment before using the production environment.

The base URL for the OTE environment is :

https://ote-api.nameshield.net/

Authentication​

You will need an API token to authenticate with the Nameshield API.
A valid token must be included in all requests, using the Authorization request header field with the Bearer authorization scheme.

Authorization: Bearer 11058cd6-ea86-49cb-a380-f4617acfd5bd

To generate an API token, you must first have a Nameshield account with the right to access the API.
Contact your account manager to obtain it.

You can generate your first token from the token management page of your account. Then, you will be able to generate other tokens with the API.

You are allowed to use up to 10 API tokens simultaneously.
If one of them is compromised or if you want to roll your API tokens regularly, you can revoke them at any time.

Rate Limiting​

The Nameshield API sets a maximum of 600 requests in a five minute period.
This limit is tracked per token.
You can verify if the limit is exceeded by checking the HTTP header of the API responses.

Retry-After: 297

Responses​

The status of a response can be determined from the HTTP status code.
The HTTP 200 or HTTP 201 status code indicates that the request has succeeded.

Successful responses will contain a JSON object with a message key.
Depending on the endpoint, if data is returned, it will be added in a data element which can contain either a single JSON object or a list of JSON objects.

{
    "message": "Created",
    "data": {
        "id": "55555",
        "name": "",
        "type": "A",
        "data": "192.168.0.0"
    }
}

Error responses will be returned as a JSON object with a list of potential errors.
An error object will contain at least a code key and a message key. An additional details object can be included to provide more information.

{
    "errors": [
        {
            "code": "INVALID_INPUT",
            "message": "Error on field type : The type field can only contain : NS, CNAME, TXT, PTR, NAPTR, RP, MX, A, AAAA, SRV, SPF, LOC, SSHFP, CAA",
            "details": {
              "field": "type"
            }
        }
    ]
}

Unicode Data​

The API does not accept Unicode characters in domain or zone names.
You must encode them in Punycode format : Punycode.