Overview

Welcome to the 4b42 API! Our API allows you to easily access your 4b42 account, get information about your products.

What should I know before starting?

Our API is continuously being developed and improved, but we are still trying to keep it as stable as possible. We try to only have changes that are backwards compatible: usually the changes are only additions, e.g. new resources are implemented or new properties are added to existing resources. Sometimes breaking changes cannot be avoided, e.g. when a new feature requires an incompatible change to the underlying data model, all those changes will be documented in the change log.

Methods

We use the following methods for our api:

Method Type Meaning
post Create Create a new instance
get Read Query/list instances
put Update Update a specific instance
delete Delete Delete a specific instance

Errors

When an error is encountered you will receive an HTTP status code along with a message and error code in the body of the response. The message is intended to give a user-friendly explanation of the error while the error codes are designed to be machine readable codes that applications can use to better understand the context of the error and react appropriately.

We use the following status codes for errors:

Status Codes

Status Code Meaning
200 OK - Request successful executed.
400 Bad request - The request contains errors.
401 Unauthorized - The authentication process failed, or the access token is not valid.
403 Forbidden - Access to this resource is restricted for the given caller.
404 Not Found - The specified resource could not be found.
405 Method Not Allowed - An invalid method was used to access a resource.
406 Not Acceptable - An unsupported format was requested.
409 Conflict - The requested operation on the resource cannot be made due the resource state.
500 Internal Server Error - There was a problem with the API host server. Try again later.
503 Service Unavailable - API is temporarily offline for maintenance. Try again later.

Error Codes

Error Code Meaning
AUTH_REQUIRED Authentication required, please authenticate with apikey or username or password.
CONNCECTION_FAILED Connection to destination failed.
CUSTOMER_CREATE_FAILED Failed to create customer
DNS_CONFIG_CREATE_FAILED Failed to create dns configuration file.
DNS_RECORD_ALREADY_EXIST DNS Deamon reload failed!
DNS_RELOAD_FAILED DNS Deamon reload failed!
DNS_SYNC_CREATE_FAILED Failed to synchronize dns zonefile with slave servers.
DNS_SYNC_DELETE_FAILED Failed to synchronize dns zonefile with slave servers.
DNS_ZONE_CREATE_FAILED Failed to create dns zonefile, please contact our support.
DNS_ZONE_DELETE_FAILED Failed to delete dns zonefile.
DNS_ZONE_REMOVE_FAILED Failed to remove zonefile or signed zonefiles, please contact our support.
DNS_ZONE_SIGN_FAILED Failed to sign dns zonefile, dnssec not enabled.
FEATURE_LIMIT_REACHED You reached the limit of your product feature, please upgrade your product.
FIELDS_EMPTY All fields are empty, you must complete at least one field.
GROUP_DOES_NOT_EXIST Requested group does not exist, please verify your input.
INVALID_AUTH No apikey or username and password used in the header. Please verify your submitted headers.
INVALID_APIKEY The apikey sent in the header is wrong or inactive. Please make sure your apikey are correct.
INVALID_CUSTOMER_NUMBER The customer number is invalid (only numbers with 8 digits) or does not exist.
INVALID_EMAIL Invaild E-Mail Address specified, please verify submitted domain name.
INVALID_FQDN Invaild FQDN, please verify submitted domain name.
INVALID_ID Invaild ID, please verify submitted id.
INVALID_PARAMETER Parameter is empty or invalid.
INVALID_URL URL is incorret or was not found.
INVALID_USER_OR_PASS Username or password are incorrect, please verify your username and password.
METHOD_RESTRICTED You do not have permission to use this method using the token that you supplied.
NETWORK_CREATE_FAILED Failed to create network
NETWORK_DELETE_FAILED Failed to remove network from server, please try again later.
ORDERING_NOT_ENABLED In order to use our API for orders, please activate this function first via our website under access.
PATH_RESTRICTED You do not have permission to use this path using the token that you supplied.
PERMISSION_DENIED You doesn't have permission to access the desired data.
RESELLER_REQUIRED Permissson denied, you have to be a member of a reseller group.
SQL_INSERT_ERROR SQL Insert Query failed, please contact our support team
SQL_UPDATE_ERROR SQL Update Query failed.
SQL_DELETE_ERROR SQL Delete Query failed.
UPN_ALREADY_EXIST UPN-Suffix already exist.
UPN_CONFIG_FAILED UPN-Suffix configuration could not be saved, please contact our support team.
USER_DOES_NOT_EXIST Requested user does not exist, please verify your input.
ZONE_ALREADY_IN_USE This zonename is already in use.

Changelog

2018-05-17 Group functions added
Functions added to manage (create,delete,lists and modify) groups of customers.

2018-03-09 Order over API must be granted
Now orders over the API can only made, if the option was enabled. This can be made on our website under access.

2018-03-08 Order Backup added
Added backup products to API.

2018-03-03 API Authentication
Updated authentication to support multible tokens with path and method permissions.

2018-03-02 API Error Codes defined
Defined API error codes for authentication, methods and paths.

2018-01-28 Tools Blacklist added
Created functions for domain and ip-address blacklist.

2017-11-24 Customer functions added
Added function GET to list all customers and details of a customer, added POST to create new customers and DELETE to remove customers

2017-04-14 API Authentication
Added API key authentication to our api.

2017-03-27 API Structure and Overview
Created the basic API structure, overview navication and content.

Authentication

All requests to the 4b42 API must be authenticated via API key. Include your secret API key in every request you send to the API with the 4b42-KEY HTTP header.

API Key

Once you have the 4b42 apie key, you can make the request to the api. To do this, add your api key to the request header.

get curl --header "4b42-KEY:hVQ8UPC3TZOrqWe9bM1nk4m27" https://api.securebit.ch/v1

To create a new API key for your project, visit the 4b42 website choose access, go to tokens, and create a new token.

manage/server/virtual

GET List

List all available Domain Name System Zones

GET /v1/manage/server/virtual
[
    {
        "id": "4b42.com",
        "updated": "2018-03-03 03:03:03",
        "valid": "yes"
    },
    {
        "id": "4b42.local",
        "updated": "2018-03-03 03:03:03",
        "valid": "yes"
    }
]

GET Details

List all available Domain Name System Zones

GET /v1/manage/server/virtual/{pid}
{
    "id": "4b42.com",
    "created": "2018-03-03 03:03:03",
    "dnssec": "0",
    "expire": "3600000",
    "hostmaster": "hostmaster.4b42.com",
    "refresh": "86400",
    "retry": "7200",
    "serial": "2018030301",
    "ttl": "172800",
    "updated": "2018-03-03 03:03:03",
    "valid": "yes"
}
Parameter
fieldtypedescriptionvalue
pidString 

GET Ticket

Generate a ticket for console session

GET /v1/manage/server/virtual/{pid}/ticket
{
    "id": "4b42.com",
    "created": "2018-03-03 03:03:03",
    "dnssec": "0",
    "expire": "3600000",
    "hostmaster": "hostmaster.4b42.com",
    "refresh": "86400",
    "retry": "7200",
    "serial": "2018030301",
    "ttl": "172800",
    "updated": "2018-03-03 03:03:03",
    "valid": "yes"
}
Parameter
fieldtypedescriptionvalue
pidString 

POST Zone

Create new dns zone

POST /v1/manage/bind/{productid}/zone
{
    "id": "4b42.local",
    "created": "2018-03-03 03:03:03",
    "dnssec": "0",
    "expire": "3600000",
    "hostmaster": "hostmaster.4b42.com",
    "refresh": "86400",
    "retry": "7200",
    "serial": "2018030301",
    "ttl": "172800",
    "updated": "2018-03-03 03:03:03",
    "valid": "yes"
}
Parameter
fieldtypedescriptionvalue
productidString 
nameStringName of zone or domainname
dnssecoptionalBoolenable or disable dnssec, default 0
expireoptionalNumberset expire time, default 3600000
hostmasteroptionalStringset hostmaster email address
refreshoptionalNumberset refresh time, default 86400
retryoptionalNumberset retry time, default 7200
ttloptionalNumberset ttl, default 172800

PUT Zone

Update dns zone details, returns updated fields

PUT /v1/manage/bind/{productid}/zone/{zone}
{
    "hostmaster": "hostmaster.4b42.com"
}
Parameter
fieldtypedescriptionvalue
productidString 
zoneString 
dnssecoptionalBoolenable or disable dnssec, default 0
expireoptionalNumberset expire time, default 3600000
hostmasteroptionalStringset hostmaster email address
refreshoptionalNumberset refresh time, default 86400
retryoptionalNumberset retry time, default 7200
ttloptionalNumberset ttl, default 172800

DELETE Zone

Remove a specified dns zone

DELETE /v1/manage/bind/{productid}/zone/{zone}
true
Parameter
fieldtypedescriptionvalue
productidString 
zoneString