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:
- Values in %% are variables
- The value yourdomain.tld should be replaced with your own domain name.
- All other symbols are literals
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
- Get a Delegation Signer Record
- List Delegation Signer Records
- Delete Delegation Signer Records
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
