DNSSEC Delegation Signer Webservice API

GKG.NET offers a RESTful webservice for managing your DNSSEC Delegation Signer records. All request and response bodies are JSON documents.

URI and JSON templates in this document are represented as follows:

All errors use JSON to supplement their status codes: {"details":"%message%"}

Authentication

Basic Authentication for this webservice is deprecated!

NOTE: Previous versions of this webservice used HTTP Basic authentication. Although Basic authentication is still supported, users are strongly encouraged to migrate to token based authentication.

All requests are authenticated using a token style API key. Each API method has its own set of access requirements that must be present in the API key.

You can generate API keys for your account at:
https://www.gkg.net/protected/contact/api-keys

Note that API keys are linked to your specific account. Your API key will not work with another users domain names.

API Keys must be sent with your requests in the Authorization header as follows:

Authorization: Bearer eyJ...

Failure to provide an API key in the Authorization header will result in a 401 Unauthorized response from the server. If the API key is not linked with a user associated with the domain you are attempting to query or modify, then a 403 Forbidden response will be returned. If the API key does not contain the required permissions for the current operation, a 403 Forbidden response is returned. For example, sending a POST request to https://www.gkg.net/ws/domain/yourdomain.com/ds with an API key that does not have the write:ds permission will result in a 403 Forbidden response.

API Methods

The following API methods are available:

Create a Delegation Signer Record

In order to create a new DS record in your domain account, you need to use the POST method on the domain.

Request

Required API Key Permissions
write:ds
URL
https://www.gkg.net/ws/domain/yourdomain.tld/ds
Method
POST
Headers
  • Accept: application/json
  • Content-Type: application/json
Request Body
{ "digest":"625F055ACB65C8B60AD18B3640062E8C23A5FD89", "digestType":"1", "algorithm":"3", "keyTag":"12345", "maxSigLife":"3456000" }

Response

On success, a 201 Created response is returned along with the location header containing the URL of the newly created Delegation Signer Record. The response body is a JSON representation of the created object.

The 415 Unsupported Media Type error is returned if an incorrect JSON string is sent.

The 422 Unprocessable Entity error is returned if the sent JSON is syntactically correct but cannot be processed due to validation errors or server policy. The details field in the JSON response will contain the reason why the request could not be processed.

Possible Status Codes
  • 201 Created
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 415 Unsupported Media Type
  • 422 Unprocessable Entity
Headers
  • Content-Type: application/json
  • Location: https://www.gkg.net/ws/domain/yourdomain.tld/ds/%digest%
Response Body
{ "digest":"625F055ACB65C8B60AD18B3640062E8C23A5FD89", "digestType":"1", "algorithm":"3", "keyTag":"12345", "maxSigLife":"3456000" }

Get A Delegation Signer Record

In order to retrieve a specific DS record, you need to use the GET method on the DS record's url.

Request

Required API Key Permissions
read:ds
URL
https://www.gkg.net/ws/domain/yourdomain.tld/ds/%digest%
Method
GET
Headers
  • Accept: application/json

Response

On success, a 200 OK response is returned, along with a JSON representation of the record.

Possible Status Codes
  • 200 OK
  • 401 Unauthorized
  • 404 Not Found
Headers
  • Content-Type: application/json
Response Body
{ "digest":"625F055ACB65C8B60AD18B3640062E8C23A5FD89", "digestType":"1", "algorithm":"3", "keyTag":"12345", "maxSigLife":"3456000" }

List Delegation Signer Records

In order to retrieve all DS records for a domain, you need to use the GET method on the domain's URL.

Request

Required API Key Permissions
read:ds
URL
https://www.gkg.net/ws/domain/yourdomain.tld/ds
Method
GET
Headers
  • Accept: application/json

Response

On success, a 200 OK response is returned, along with a JSON array containing the list of DS records associated with the domain.

Possible Status Codes
  • 200 OK
  • 401 Unauthorized
  • 404 Not Found
Headers
  • Content-Type: application/json
Response Body
[ { "digest":"625F055ACB65C8B60AD18B3640062E8C23A5FD89", "digestType":"1", "algorithm":"3", "keyTag":"12345", "maxSigLife":"3456000" }, { "digest":"1234555ACB65C8B60AD18B3640062E8C23A5FD89", "digestType":"1", "algorithm":"3", "keyTag":"54321", "maxSigLife":"3456000" } ]

Delete A Delegation Signer Record

In order to delete a DS record from a domain, you need to use the DELETE method on the DS record's URL.

Request

Required API Key Permissions
write:ds
URL
https://www.gkg.net/ws/domain/yourdomain.tld/ds/%digest%
Method
DELETE

Response

On success, a 204 No Content response is returned. There is no response body

Possible Status Codes
  • 204 No Content
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found