HN SSC API (0.0.1)

Download OpenAPI specification:

E-mail: info@netzhoster.de URL: http://netzhoster.de/ssc-api

This documents the API provided by WK-Serv/Netzhoster to be used by its own customer SSC as well as direct connections from customer's infrastructure.

Generic funtione

sends "pong" back to client

just a simple ping to ensure server (and authentification) are working

Authorizations:

BasicAuthBearerAuth

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": "authorized pong"
}

requests token to be used for GUI/TUI access

performs authentification of the user and respnses with an API-token to be used as authorization for GUI/TUI acces (preventing sending credentials on every request). Usage of token is mandatory if user has 2FA configured

Authorizations:

BasicAuth

Responses

Response samples

200
202

Content type

application/json

{"status": "success",
"data": {"token": "cc8a96f0-7f1a-44b2-b5e1-23d2b9f607fa",
"userinfo": {"displayName": "Max Mustermann",
"allowedModules": {"GEN": 1023,
"ACC": 1023,
"DNS": 1023,
"DOM": 1023
}
}
}
}

delets login token (logout)

deletes login token from database, no further requests authorised

Authorizations:

BearerAuth

Responses

sends 2FA authentification details

sends 2FA information to finish login/token request

Authorizations:

BearerAuth

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"otpType": 3,
"otp": "xXxXxX"
}

Response samples

200

Content type

application/json

{"status": "success",
"data": {"token": "cc8a96f0-7f1a-44b2-b5e1-23d2b9f607fa",
"userinfo": {"displayName": "Max Mustermann",
"allowedModules": {"GEN": 1023,
"ACC": 1023,
"DNS": 1023,
"DOM": 1023
}
}
}
}

initiating password reset process (step 1/2)

initiates password reset process: sending reset-code via email; Attention for BasicAuth: "user" has to be the user login, "password" to be set to the users contact email address

Authorizations:

BasicAuth

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": {"token": "03e3bd6c-3056-493e-8fed-0fc883d80cf8",
"Auth2FA": [1,
2
],
"userinfo": {"displayName": "Max Mustermann"
}
}
}

finalise password reset process (step 2/2)

finalise password reset by checking security code and setting new password (no auto-login!)

Authorizations:

BearerAuth

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"resetCode": "xXxXxX",
"newPassword": "changeMeNew1234",
"otpType": 3,
"otp": "xXxXxX"
}

Response samples

200

Content type

application/json

{"status": "success"
}

sets new password for user

Authorizations:

BearerAuthBasicAuth

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"newPassword": "changeMeNew1234"
}

Response samples

200

Content type

application/json

{"status": "success"
}

setting configuration for 2FA autentification (step 1/2)

initiates 2FA configuration process: requesting setup for specific otpType. any existing configuration for given otpType will be overwritten after confirmation!

Authorizations:

BearerAuthBasicAuth

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

Example

for Google Authenticator

{"otpType": 1
}

Response samples

202

Content type

application/json

Example

for Google Authenticatior

{"status": "success",
"data": {"otpType": 1,
"qrcode": "<data-url-style image>",
"cdata": {"secret": "xXxXxX",
"issuer": "Netzhoster SSC",
"label": "aaa-muster2 (Max Mustermann)"
}
}
}

finalise 2FA setup (step 2/2)

finalise 2FA setup by confirming otp method offers valid token

Authorizations:

BearerAuth

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"otpType": 3,
"otp": "xXxXxX"
}

Response samples

200

Content type

application/json

{"status": "success"
}

deletes 2FA configuration for given otpType for current user

Authorizations:

BearerAuth

path Parameters

otpType

required

integer

type of otp to delete

Responses

Response samples

200

Content type

application/json

{"status": "success"
}

get customer overview

get list all available customer this user is allowed to act on

Authorizations:

BearerAuthBasicAuth

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": {"currentCustomer": 1,
"customers": [{"uid": 2,
"customerID": 10344,
"customerName": "Customer 1 GmbH",
"customerPrefix": "dee"
},
{"uid": 3,
"customerID": 12157,
"customerName": "Scrooge McDuck plc",
"customerPrefix": "vz7"
},
{"uid": 1,
"customerID": 10000,
"customerName": "ACME BV",
"customerPrefix": "aaa"
}
]
}
}

User account management

returns list of login accounts associated with current user

Authorizations:

BearerAuthBasicAuth

query Parameters

sub	boolean false (default): only current customer is looked at, true: customers belonging to current customer are included

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": [{"id": 1,
"login": "00000,",
"displayName": "Masteruser Kd 10000",
"contact": "me@example.com",
"modules": {"GEN": 1023,
"ACC": 1023,
"DNS": 1023,
"DOM": 1023
},
"active": true,
"customerName": "Scrooge McDuck plc"
},
{"id": 9,
"login": "xxx-user,",
"displayName": "Max Mustermann",
"contact": "user1@example.com",
"modules": {"GEN": 255,
"ACC": 127,
"DOM": 1023
},
"active": true,
"customerName": "Scrooge McDuck plc"
}
]
}

set password for specified user

Authorizations:

BearerAuthBasicAuth

path Parameters

uid

required

string

uid of account to set password for, can be numeric userID (eg. 7, PREFERRED) or userNAME (eg. aaa-muster1, does not work for numeric primary users)

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"newPassword": "xXxXxX"
}

Response samples

200

Content type

application/json

{"status": "success"
}

changes active status on user login

Authorizations:

BearerAuthBasicAuth

path Parameters

uid

required

integer

uid of account to set password for

query Parameters

active

required

boolean

true/false

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"newPassword": "xXxXxX"
}

Response samples

200

Content type

application/json

{"status": "success"
}

create new user account

WARNING: function still in development!

creates new user account. if customer is omitted in request body the current customer is assumed; if modules is omitted, current users module permissions are copied 1:1; if modules is set permissions are set in extend to the customers privilege levels.

given userame will be prepended by customer prefix automatically

Authorizations:

BearerAuthBasicAuth

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"login": "exampleuser",
"password": "xXxXxX",
"displayName": "John Doe",
"contact": "john.doe@example.com",
"active": true,
"customer": "optional",
"modules": {"GEN": 37
}
}

Response samples

200

Content type

application/json

{"status": "success",
"data": "xxx-exampleuser"
}

deletes user login

Authorizations:

BearerAuthBasicAuth

path Parameters

uid

required

integer

uid of account to delete (numeric uid PREFERRED)

Responses

Response samples

200

Content type

application/json

{"status": "success"
}

Domain registration

check domain availability

Authorizations:

BearerAuthBasicAuth

path Parameters

domain

required

string

name of domain to check

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": {"domain": "example.org",
"sld": "example",
"tld": "org",
"available": false
}
}

check domain availability

Authorizations:

BearerAuthBasicAuth

path Parameters

tld required	string tld (top-level-domain) to check
sld required	string sld (second-level-domain) to check

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": {"domain": "example.org",
"sld": "example",
"tld": "org",
"available": false
}
}

retrieved list of registered domains

Authorizations:

BearerAuthBasicAuth

query Parameters

sub	boolean false (default): only current customer is looked at, true: customers belonging to current customer are included
recursive	boolean false (default): only fist sub-customer-level is checked, true: customers are collected recursively (include sub*-sub-customers)
deleted	boolean include deleted (marked as deleted) domains
limittld	string limit list to given tld(s) (comma-separated)

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": [{"id": 3,
"sld": "org",
"tld": "example",
"billedUntil": "2026-01-01",
"owner": {"uid": 1,
"customerID": 99999,
"customerName": "Scrooge McDuck plc"
}
},
{"id": 1,
"sld": "com",
"tld": "example",
"billedUntil": "2026-01-01",
"owner": {"uid": 1,
"customerID": 99999,
"customerName": "Scrooge McDuck plc"
}
}
]
}

DNS Zone management

returns list of DNS zones for customer(s)

Authorizations:

BearerAuthBasicAuth

query Parameters

sub	boolean false (default): only current customer is looked at, true: customers belonging to current customer are included

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": [{"id": 5,
"zone": "dns-verwaltung.de",
"type": "i",
"owner": {"uid": 1,
"customerID": 99999,
"customerName": "Scrooge McDuck plc"
},
"dnssec": true
},
{"id": 6,
"zone": "example.aero",
"type": "e",
"owner": {"uid": 1,
"customerID": 99999,
"customerName": "Scrooge McDuck plc"
},
"dnssec": null
}
]
}

create new DNS zone

Authorizations:

BearerAuthBasicAuth

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"name": "example.org",
"type": "e",
"owner": 3
}

Response samples

200

Content type

application/json

{"status": "success"
}

get zone details

Authorizations:

BearerAuthBasicAuth

path Parameters

zone

required

string

name of DNS zone to get

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": {"zone": {"id": 5,
"zone": "dns-verwaltung.de",
"type": "i",
"dnssec": true,
"owner": {"uid": 1,
"customerID": 99999,
"customerName": "Scrooge McDuck plc"
}
},
"records": {"A": [{"id": 25,
"name": "dns-verwaltung.de",
"content": "89.58.78.168",
"prio": 0,
"ttl": 60,
"disabled": false,
"dyndns": null
},
{"id": 27,
"name": "test.dns-verwaltung.de",
"content": "4.5.6.7",
"prio": 0,
"ttl": 7200,
"disabled": false,
"dyndns": null
}
],
"AAAA": [{"id": 37,
"name": "test.dns-verwaltung.de",
"content": "fe80::1",
"prio": null,
"ttl": 7200,
"disabled": false,
"dyndns": null
}
],
"SOA": [{"id": 26,
"name": "dns-verwaltung.de",
"content": "ns1.wk-serv.de hostmaster@wk-serv.de 2026090203 10800 3600 604800 7200",
"prio": 0,
"ttl": 7200,
"disabled": false,
"dyndns": null
}
],
"NS": [{"id": 17,
"name": "dns-verwaltung.de",
"content": "ns2.wk-serv.de",
"prio": null,
"ttl": 7200,
"disabled": false,
"dyndns": null
},
{"id": 18,
"name": "dns-verwaltung.de",
"content": "ns3.wk-serv.net",
"prio": null,
"ttl": 7200,
"disabled": false,
"dyndns": null
}
]
},
"dnsupdateKeys": ["aaa-dnsupdate",
"aaa-test3"
]
}
}

modify zone

modify owner and type of zone (omitted details will be unchanged)

Authorizations:

BearerAuthBasicAuth

path Parameters

zone

required

string

name of DNS zone to modify

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"owner": 7,
"type": "e"
}

Response samples

200

Content type

application/json

{"status": "success"
}

delete zone

deletes dns zone including ressource records and dnsupdate/dyndns-ACL

Authorizations:

BearerAuthBasicAuth

path Parameters

zone

required

string

name of DNS zone to delete

Responses

Response samples

200

Content type

application/json

{"status": "success"
}

toggle DNSSEC enabled

togggles status of DNSSec for zone:

requests craetion/removal of DNSSec keys
if applicable: updates domain with registry

Authorizations:

BearerAuthBasicAuth

path Parameters

zone

required

string

name of DNS zone to set DNSSec for

Responses

Response samples

202

Content type

application/json

{"status": "success"
}

retrieve DNSSEC details

retrieves current DNSSec-information for zone (keys, dn-/dnskey-records, nsec3 information)

Authorizations:

BearerAuthBasicAuth

path Parameters

zone

required

string

name of DNS zone to get DNSSec information for

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": {"dnskey": [{"content": "257 3 13 a0/iK8dJ96Zkv5nkS7GKyl8igqfSFvIELcCAEdlaZtzBLuAKh/8tuXowmlQHWPUMiVPJ3QjzHe4ehQi4DqnojQ== ; ( ECDSAP256SHA256 )"
}
],
"ds": [{"content": "31211 13 2 e7afbe9059c30833f6849b8238c5706ef211215e5e77c35dac017d5c7e1b40e1 ; ( SHA256 digest )"
},
{"content": "31211 13 4 f881c58142bd24cf0c6c3ddc5a50716774a464e619c0e846bfa531103e540ffdbf2e1a07cccda17d92178d2543735304 ; ( SHA-384 digest )"
}
],
"key": [{"type": 257,
"algorithm": 13,
"length": 256,
"active": true,
"tag": 31211,
"id": 1
}
],
"zone": {"id": 5,
"zone": "dns-verwaltung.de",
"type": "i",
"owner": 1
}
}
}

add TSigKey to zone

Authorizations:

BearerAuthBasicAuth

path Parameters

zone required	string name of DNS zone to modify
keyname required	string name of TSigKey to add to allow-list

Responses

Response samples

200

Content type

application/json

{"status": "success"
}

remove TSigKey from zone

Authorizations:

BearerAuthBasicAuth

path Parameters

zone required	string name of DNS zone to modify
keyname required	string name of TSigKey to remove from allow-list

Responses

Response samples

200

Content type

application/json

{"status": "success"
}

DNS Record management

create new record in DNS zone

Authorizations:

BearerAuthBasicAuth

path Parameters

zone

required

string

name of DNS zone to put record in

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"name": "sub.example.org",
"type": "A",
"content": "127.0.0.1",
"ttl": 7200,
"prio": 0,
"disabled": false
}

Response samples

200

Content type

application/json

{"status": "success"
}

get ressource record

Authorizations:

BearerAuthBasicAuth

path Parameters

zone required	string name of DNS zone to modify
recordid required	integer id of record to delete

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": {"id": 27,
"type": "A",
"name": "test.dns-verwaltung.de",
"content": "4.5.6.7",
"prio": 0,
"ttl": 7200,
"disabled": false
}
}

modify ressource record

modifies/patches given ressource record, all data omitted in request body will be unchanged

Authorizations:

BearerAuthBasicAuth

path Parameters

zone required	string name of DNS zone to modify
recordid required	integer id of record to modify

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"content": "127.0.0.1",
"ttl": 7200,
"prio": 0
}

Response samples

200

Content type

application/json

{"status": "success"
}

delete ressource record

Authorizations:

BearerAuthBasicAuth

path Parameters

zone required	string name of DNS zone to modify
recordid required	integer id of record to delete

Responses

Response samples

200

Content type

application/json

{"status": "success"
}

enable/disable record (toggle setting)

Authorizations:

BearerAuthBasicAuth

path Parameters

zone required	string name of DNS zone to modify
recordid required	integer id of record to en-/disable

Responses

Response samples

200

Content type

application/json

{"status": "success"
}

get dyndns-ACL for record

retrieves list of users allowed to modify this record using the DynDNS-protocol

Authorizations:

BearerAuthBasicAuth

path Parameters

zone required	string name of DNS zone to modify
recordid required	integer id of record to retieve data for

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": {"dyndnsUsers": ["aaa-muster1",
"aaa-muster2"
]
}
}

delete dyndns-ACL for record

deletes user(s) from list of users allowed to modify this record using the DynDNS-protocol

Authorizations:

BearerAuthBasicAuth

path Parameters

zone required	string name of DNS zone to modify
recordid required	integer id of record to delete ACL for

Responses

Response samples

200

Content type

application/json

{"status": "success"
}

sets dyndns-ACL for record

adds user(s) to list of users allowed to modify this record using the DynDNS-protocol

Authorizations:

BearerAuthBasicAuth

path Parameters

zone required	string name of DNS zone to modify
recordid required	integer id of record to delete ACL for

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"dyndnsUsers": ["aaa-muster1"
]
}

Response samples

200

Content type

application/json

{"status": "success"
}

perform DynDNS update

Authorizations:

BasicAuth

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"ip": "127.0.0.1",
"hostname": ["dyn.example.org",
"dyn.example.net"
]
}

Response samples

200

Content type

application/json

{"status": "success"
}

get fwdServer configuration

Authorizations:

BearerAuthBasicAuth

path Parameters

zone required	string name of DNS zone
hostname required	string hostname to get configuration for

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": {"hostname": "forward.dns-verwaltung.de",
"type": "h",
"target": "https://www.wk-serv.de",
"title": null
}
}

sets fwdServer configuration

Authorizations:

BearerAuthBasicAuth

path Parameters

zone required	string name of DNS zone
hostname required	string hostname to get configuration for

query Parameters

force

boolean

configure fwdServer even if A/AAAA-records for hostname exist and not point to fwdServer

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"type": "h",
"target": "https://www.wk-serv.de",
"title": null
}

Response samples

200

Content type

application/json

{"status": "success"
}

delete fwdServer configuration

Authorizations:

BearerAuthBasicAuth

path Parameters

zone required	string name of DNS zone
hostname required	string hostname to get configuration for

Responses

Response samples

200

Content type

application/json

{"status": "success"
}

TSig-Key management

returns list of TSigKeys for customer(s)

Authorizations:

BearerAuthBasicAuth

query Parameters

sub	boolean false (default): only current customer is looked at, true: customers belonging to current customer are included

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": [{"id": 1,
"name": "aaa-dnsupdate",
"algorithm": "hmac-sha512",
"owner": {"uid": 1,
"customerID": 99999,
"customerName": "Scrooge McDuck plc"
}
},
{"id": 8,
"name": "aaa-test3",
"algorithm": "hmac-sha256",
"owner": {"uid": 1,
"customerID": 99999,
"customerName": "Scrooge McDuck plc"
}
}
]
}

request generation of new TSigKey

request generation of new TSigKey with given name (customer prefix automatically added) and algorithm. Key is generated asynchronously and can be retieved later

owner is optional - will be assumed as current customer if omitted

allowed algorithms are:

hmac-md5
hmac-sha1
hmac-sha224
hmac-sha256
hmac-sha384
hmac-sha512

Authorizations:

BearerAuthBasicAuth

Request Body schema: application/json

Schema not provided

Responses

Request samples

Payload

Content type

application/json

{"name": "examplekeyname",
"owner": 3,
"algorithm": "hmac-sha512"
}

Response samples

202

Content type

application/json

{"status": "success"
}

retieve TSigKey

returns named TSigKey as unencrypted string

Authorizations:

BearerAuthBasicAuth

path Parameters

keyname

required

string

name of TSigKey to retrieve

Responses

Response samples

200

Content type

application/json

{"status": "success",
"data": "VUVAC0\\/c+hme48dwxRtzjz2QF8\\/PlwM2d8RBsmQfL+6sz2PbLt+\\/5DVzIwQbt8DAq79tFLDqW9A+vjsRfUTSaQ=="
}

delete TSigKey

Authorizations:

BearerAuthBasicAuth

path Parameters

keyname

required

string

name of TSigKey to delete

Responses

Response samples

202

Content type

application/json

{"status": "success"
}