TSIGKeys

Added in version 4.2.0.

TSIGKeys can be manipulated via the API.

TSIGKey Endpoints

GET /servers/{server_id}/tsigkeys

Get all TSIGKeys on the server, except the actual key

Parameters:

  • server_id (string) – The id of the server to retrieve

Example request:

GET /servers/{server_id}/tsigkeys HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    List of TSIGKey objects

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "name": "string",
        "id": "string",
        "algorithm": "string",
        "key": "string",
        "type": "string"
    }
]

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

POST /servers/{server_id}/tsigkeys

Add a TSIG key

This methods add a new TSIGKey. The actual key can be generated by the server or be provided by the client

Parameters:

  • server_id (string) – The id of the server to retrieve

Example request:

POST /servers/{server_id}/tsigkeys HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "algorithm": "string",
    "key": "string"
}
Status Codes:

  • 201 Created –

    Created

    Example response:

    HTTP/1.1 201 Created
Content-Type: application/json

{
    "name": "string",
    "id": "string",
    "algorithm": "string",
    "key": "string",
    "type": "string"
}

  • 409 Conflict –

    An item with this name already exists

    Example response:

    HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

GET /servers/{server_id}/tsigkeys/{tsigkey_id}

Get a specific TSIGKeys on the server, including the actual key

Parameters:

  • server_id (string) – The id of the server to retrieve

  • tsigkey_id (string) – The id of the TSIGkey. Should match the “id” field in the TSIGKey object

Example request:

GET /servers/{server_id}/tsigkeys/{tsigkey_id} HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    OK.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "string",
    "id": "string",
    "algorithm": "string",
    "key": "string",
    "type": "string"
}

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

PUT /servers/{server_id}/tsigkeys/{tsigkey_id}
The TSIGKey at tsigkey_id can be changed in multiple ways:

  • Changing the Name, this will remove the key with tsigkey_id after adding.

  • Changing the Algorithm

  • Changing the Key

Only the relevant fields have to be provided in the request body.

Parameters:

  • server_id (string) – The id of the server to retrieve

  • tsigkey_id (string) – The id of the TSIGkey. Should match the “id” field in the TSIGKey object

Example request:

PUT /servers/{server_id}/tsigkeys/{tsigkey_id} HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "string",
    "algorithm": "string",
    "key": "string"
}
Status Codes:

  • 200 OK –

    OK. TSIGKey is changed.

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "string",
    "id": "string",
    "algorithm": "string",
    "key": "string",
    "type": "string"
}

  • 409 Conflict –

    An item with this name already exists

    Example response:

    HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

DELETE /servers/{server_id}/tsigkeys/{tsigkey_id}

Delete the TSIGKey with tsigkey_id

Parameters:

  • server_id (string) – The id of the server to retrieve

  • tsigkey_id (string) – The id of the TSIGkey. Should match the “id” field in the TSIGKey object

Status Codes:

  • 204 No Content – OK, key was deleted

  • default –

    The input to the operation was not valid

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "error": "string",
    "errors": [
        "string"
    ]
}

Objects

json TSIGKey : object

TSIGKey

A TSIG key that can be used to authenticate NOTIFY, AXFR, and DNSUPDATE queries.

Optional members:
algorithm : string

The algorithm of the TSIG key

id : string

The ID for this key, used in the TSIGkey URL endpoint.

key : string

The Base64 encoded secret key, empty when listing keys. MAY be empty when POSTing to have the server generate the key material

name : string

The name of the key

type : string

Set to “TSIGKey”

Examples

Generating a new TSIG key

POST /servers/localhost/tsigkeys HTTP/1.1
X-Api-Key: secret
Content-Type: application/json

{"name": "mytsigkey", "algorithm": "hmac-sha256"}

Will yield a response similar to this (several headers omitted):

HTTP/1.1 201 Created
Content-Type: application/json

{"algorithm": "hmac-sha256", "id": "mytsigkey.", "key": "ayZmdUpT5xh7H21p3UUHJWZgF2F2jNncqx5SQkRIWbqReuwieiVBG8jtEieb/njCbjrLtQkjVsgoiKCtsqNsdQ==", "name": "mytsigkey", "type": "TSIGKey"}

Modifying the key material

PUT /servers/localhost/tsigkeys/mytsigkey. HTTP/1.1
X-Api-Key: secret
Content-Type: application/json

{"name": "mytsigkey", "key": "GQNyFy1QagMUarHmiSgsIJajghdTGJGVcN5TRVwgbclzxGyhQR1uYLCOyJ/uj9uj12jyeLwzJuW12wCI9PYv7Q=="}

HTTP/1.1 200 Ok
Content-Type: application/json

{"algorithm": "hmac-sha256", "id": "mytsigkey.", "key": "GQNyFy1QagMUarHmiSgsIJajghdTGJGVcN5TRVwgbclzxGyhQR1uYLCOyJ/uj9uj12jyeLwzJuW12wCI9PYv7Q==", "name": "mytsigkey", "type": "TSIGKey"}