Overview

This is the official documentation for the Application Programming Interface (API).

Introduction

This API operates over HTTPS and uses JSON as its data format. This API is a RESTful API and utilizes HTTP methods and HTTP status codes to specify requests and responses.

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.
402	Payment Required - You do not have enough balance to complete this transaction.
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.
422	Unprocessable Entity - Action could not be processed properly due to invalid data provided
429	Too Many Requests - Server received too many requests in a given amount of time.
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
conflict	The resource has changed during the request, please retry
forbidden	Insufficient permissions for this request
invalid_input	Error while parsing or processing the input
json_error	Invalid JSON input in your request
locked	The item you are trying to access is locked, because there is already an Action running
maintenance	Cannot perform operation due to maintenance work
not_found	Entity not found
protected	The Action you are trying to start is protected for this resource
rate_limit_exceeded	Error when sending too many requests
resource_limit_exceeded	Error when exceeding the maximum quantity of a resource for an account
resource_unavailable	The requested resource is currently unavailable
require_error	One or more of the object fields are required.
server_error	Error within the API backend
service_error	Error within a service
unauthorized	Request was made with an invalid or unknown token
unavailable	A service or product is currently not available
uniqueness_error	One or more of the objects fields must be unique
unsupported_error	The corresponding resource does not support the Action

Rate Limiting

All requests, whether they are authenticated or not, are subject to rate limiting. If you have reached your limit, your requests will be handled with a 429 Too Many Requests error. Burst requests are allowed. Responses contain serveral headers which provide information about your current rate limit status.

The RateLimit-Limit header contains the total number of requests you can perform per hour.
The RateLimit-Remaining header contains the number of requests remaining in the current rate limit time frame.
The RateLimit-Reset header contains a UNIX timestamp of the point in time when your rate limit will have recovered and you will have the full number of requests available again.

The default limit is 3600 requests per hour and per Project. The number of remaining requests increases gradually. For example, when your limit is 3600 requests per hour, the number of remaining requests will increase by 1 every second.

Authentication

All requests to the API must be authenticated via your API token. Include your API token in every request you send to the API with the Authorization HTTP header.

API-Key

To use the API-Key you just need to paste your API-Key below, after that you are ready to use the API.

API-Key

Customer

DELETE Customer

Remove a Customer

DELETE /v1/customer/{customerNumber}

true

Parameter

field	type	description	value
customerNumber	String

GET Customers

List of all customers

Feature for managed resellers only.

GET /v1/customer

[
    {
        "name": "00000001",
        "description": "Example Inc.",
        "guid": "bf06f912-62c0-41cd-9d2c-d2980a85f0e4"
    }
]

GET Customer

List Details of a specific customer

GET /v1/customer/{customerNumber}

{
    "country": "CH",
    "city": "Example",
    "state": "Sample",
    "street": "Samplestreet",
    "name": "00000005",
    "description": "Example Inc.",
    "zipcode": "12345",
    "telephonenumber": "+4112345789",
    "created": {
        "date": "2024-03-24 10:04:07.000000",
        "timezone_type": 3,
        "timezone": "UTC"
    },
    "modified": {
        "date": "2024-03-24 10:04:07.000000",
        "timezone_type": 3,
        "timezone": "UTC"
    },
    "vatid": "CHE-123.456.789",
    "streetnumber": "123"
}

Parameter

field	type	description	value
customerNumber	String

POST Customer

Create new customer

Feature for managed resellers only.

POST /v1/customer

{
    "country": "CH",
    "city": "Example",
    "state": "Sample",
    "street": "Samplestreet",
    "name": "00000005",
    "description": "Example Inc.",
    "zipcode": "12345",
    "telephonenumber": "+4112345789",
    "created": {
        "date": "2024-03-24 9:36:37.000000",
        "timezone_type": 3,
        "timezone": "UTC"
    },
    "modified": {
        "date": "2024-03-24 09:36:37.000000",
        "timezone_type": 3,
        "timezone": "UTC"
    },
    "vatid": "CHE-123.456.789",
    "streetnumber": "123"
}

Parameter

field	type	description
description	String	used for organisation name or individuals realname and firstname.
streetoptional	String	street
streetnumberoptional	String	street number
zipcodeoptional	Number	Postal code
cityoptional	String	City
stateoptional	String	State
country	String	Countrycode based on ISO-3166-1A2
telephonenumberoptional	String	phone number
mobileoptional	String	mobile number
vatidoptional	String	vat identifier

PUT Customer

Update details of a customer

PUT /v1/customer/{customerNumber}

{
    "country": "CH",
    "city": "Example",
    "state": "Sample",
    "street": "Samplestreet",
    "name": "00000005",
    "description": "Example Inc.",
    "zipcode": "1234",
    "telephonenumber": "+4112345789",
    "created": {
        "date": "2024-03-24 10:04:07.000000",
        "timezone_type": 3,
        "timezone": "UTC"
    },
    "modified": {
        "date": "2024-03-24 10:34:01.000000",
        "timezone_type": 3,
        "timezone": "UTC"
    },
    "vatid": "CHE-123.456.789",
    "streetnumber": "123"
}

Parameter

field	type	description
customerNumber	String
description	String	used for organisation name or individuals realname and firstname.
streetoptional	String	street
streetnumberoptional	String	street number
zipcodeoptional	Number	Postal code
cityoptional	String	City
stateoptional	String	State
country	String	Countrycode based on ISO-3166-1A2
telephonenumberoptional	String	phone number
mobileoptional	String	mobile number
vatidoptional	String	vat identifier

Customer/group

DELETE Group

Remove a specified user

DELETE /v1/customer/group/{customerNumber}/{groupName}

true

Parameter

field	type	description	value
customerNumber	String
groupName	String

GET Groups

List all groups of current customer

GET /v1/customer/group/{customerNumber}

[]

Parameter

field	type	description	value
customerNumber	String

GET Group

List details of selected group

GET /v1/customer/group/{customerNumber}/{groupName}

{
    "name": "Test Group",
    "members": [
        "CN=B\u00fchl\\,Kevin,OU=Users,OU=12345678,OU=Customers,DC=4b42,DC=com"
    ],
    "dn": "CN=Test Group,OU=Groups,OU=12345678,OU=Customers,DC=4b42,DC=com"
}

Parameter

field	type	description	value
customerNumber	String
groupName	String

POST Group

Create new group

POST /v1/customer/group/{customerNumber}

{
    "name": "Billing",
    "guid": "ba213358-32c9-4fdb-9caa-4e435ef1c26b"
}

Parameter

field	type	description	value
customerNumber	String
groupName	String	Name of group

PUT Group

Update details of a group

PUT /v1/customer/group/{customerNumber}/{groupName}

{
    "name": "Test Group",
    "members": [
        "CN=Mustermann\\, Max,OU=Users,OU=12345678,OU=Customers,DC=4b42,DC=com"
    ],
    "dn": "CN=Test Group,OU=Groups,OU=12345678,OU=Customers,DC=4b42,DC=com"
}

Parameter

field	type	description
customerNumber	String
groupName	String
members	String	users and groups which are members of the group (override existing)

Customer/suffix

DELETE Suffix

Remove a specified user

DELETE /v1/customer/suffix/{customerNumber}/{suffix}

true

Parameter

field	type	description	value
customerNumber	String
suffix	String

GET Suffixes

List all UPN-Suffixes for user login names (firstname.realname@4b42.com)

GET /v1/customer/suffix/{customerNumber}

{
    "id": 1,
    "created": "2018-03-10 00:48:42",
    "description": "Example Suffix",
    "suffix": "example.com",
    "uid": 1,
    "configured": true
}

Parameter

field	type	description	value
customerNumber	String

POST Suffix

Add new suffix for users user principal name for login (firstname.realname@suffix.local)

POST /v1/customer/suffix/{customerNumber}

{
    "id": "4b42.local",
    "created": "2018-03-10 00:48:42"
}

Parameter

field	type	description	value
customerNumber	String
suffix	String	Name of domain used as upn-suffix

Customer/user

DELETE User

Remove a specified user

DELETE /v1/customer/user/{userId}

true

Parameter

field	type	description	value
userId	String

GET Users

List all users of current customer

GET /v1/customer/user/{customerNumber}

[
    {
        "name": "B\u00fchl, Kevin",
        "lastname": "B\u00fchl",
        "firstname": "Kevin",
        "username": "12345678_1234",
        "upn": "12345678_1234@4b42.com",
        "dn": "CN=B\u00fchl\\, Kevin,OU=Users,OU=12345678,OU=Customers,DC=4b42,DC=com",
        "id": "12345678_1234"
    }
]

Parameter

field	type	description	value
customerNumber	String

GET User

List details of selected user

GET /v1/customer/user/{userId}

{
    "name": "Mustermann, Max",
    "lastname": "Mustermann",
    "firstname": "Max",
    "created": {
        "date": "2018-03-03 03:03:03.000000",
        "timezone_type": 3,
        "timezone": "UTC"
    },
    "modified": {
        "date": "2018-03-03 03:03:03.000000",
        "timezone_type": 3,
        "timezone": "UTC"
    },
    "dn": "CN=Mustermann\\, Max,OU=Users,OU=12345678,OU=Customers,DC=4b42,DC=com"
}

Parameter

field	type	description	value
userId	String

POST User

Create new user

POST /v1/customer/user/{customerNumber}

{
    "lastname": "Muster",
    "firstname": "Andrea",
    "password": "SecurePassword",
    "customernumber": "12345678",
    "displayname": "Muster, Andrea",
    "name": "Muster, Andrea",
    "username": "12345678_1234",
    "passwordNeverExpires": true
}

Parameter

field	type	description
customerNumber	String
lastname	String	Lastname
firstname	String	Firstname
upnoptional	String	User Principal Name
passwordoptional	String	Pasword, if empty password will be generated

PUT User

Update details of a customer

PUT /v1/customer/user/{userId}

[]

Parameter

field	type	description
userId	String
lastnameoptional	String	Lastname
firstnameoptional	String	Firstname
upnoptional	String	User Principal Name (like email max@sample.com)
passwordoptional	String	Pasword

Internet/abuse

GET Abuse

List of all internet exchanges supported

GET /v1/internet/abuse/{resource}

[]

Parameter

field	type	description	value
resource	String

Internet/abuse/report

GET Abuse

Provides an Abuse Report for requested resource as PDF

GET /v1/internet/abuse/report/{resource}

[]

Parameter

field	type	description	value
resource	String

Internet/domain_name_system/zone

POST Zone

Create new dns zone

POST /v1/internet/domain_name_system/zone

{
    "id": "1",
    "created": "2018-03-03 03:03:03",
    "dnssec": "0",
    "expire": "3600000",
    "hostmaster": "hostmaster.example.com",
    "name": "example.com",
    "refresh": "86400",
    "retry": "7200",
    "serial": "2018030301",
    "ttl": "172800",
    "updated": "2018-03-03 03:03:03",
    "valid": "yes"
}

Parameter

field	type	description
name	String	Name of zone or domainname
hostmaster	String	set hostmaster email address
dnssecoptional	Bool	enable or disable dnssec, default 0
expireoptional	Number	set expire time, default 3600000
refreshoptional	Number	set refresh time, default 86400
retryoptional	Number	set retry time, default 7200
ttloptional	Number	set ttl, default 172800

GET Zones

List all available Domain Name System Zones

GET /v1/manage/bind/{productid}/zone

[
    {
        "id": "4b42.com",
        "updated": "2018-03-03 03:03:03",
        "valid": "yes"
    },
    {
        "id": "4b42.local",
        "updated": "2018-03-03 03:03:03",
        "valid": "yes"
    }
]

Parameter

field	type	description	value
productid	String

GET Zone

List all available Domain Name System Zones

GET /v1/manage/bind/{productid}/zone/{zone}

{
    "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

field	type	description	value
productid	String
zone	String

Internet/exchange

GET Exchange

List of all internet exchanges supported

GET /v1/internet/exchange

[
    {
        "id": 1,
        "asn": 56755,
        "country": "CH",
        "description": "Securebit Internet Exchange Point",
        "name": "SBIX"
    },
    {
        "id": 2,
        "asn": 60020,
        "country": "DE",
        "description": "Rottweiler Internet Exchange",
        "name": "RWIX"
    }
]

Internet/exchange/connection

POST Connection

Create an autonomous system number

POST /v1/internet/resouces

{}

Parameter

field	type	description	value
type	String	XC=Cross Connect, VLAN=Virtual Local Area Network, VPS=
size	Number	bits of resouce (default: 48 for ipv6, 32 for asn and ipv4)

PUT Internet Resources

Update details of a customer

PUT /v1/internet/resouces/{id}

{}

Parameter

field	type	description
id	String
description	String	used for organisation name or individuals realname and firstname.
streetoptional	String	street
streetnumberoptional	String	street number
zipcodeoptional	Number	Postal code
cityoptional	String	City
stateoptional	String	State
country	String	Countrycode based on ISO-3166-1A2
telephonenumberoptional	String	phone number
mobileoptional	String	mobile number
vatidoptional	String	vat identifier

Internet/resources/autonomous_system

DELETE AS-Number

Delete an internet resource

DELETE /v1/internet/resources/asn/{id}

true

Parameter

field	type	description	value
id	String

GET Numbers

List of all autonomous system numbers

GET /v1/internet/resources/autonomous_system

{}

GET Pricing

List Details of a specific customer

GET /v1/internet/resources/autonomous_system/pricing

[
    {
        "name": "asn_pi_32bit",
        "create": "100.00000",
        "renew": "100.00000",
        "update": "100.00000"
    },
    {
        "name": "ipv4_pa_24",
        "create": "100.00000",
        "renew": "300.00000",
        "update": "0.00000"
    },
    {
        "name": "ipv6_pa_48",
        "create": "100.00000",
        "renew": "15.00000",
        "update": "0.00000"
    }
]

POST AS-Number

Create an autonomous system number

POST /v1/internet/resources/autonomous_system

{}

Parameter

field	type	description
org	String	ORG-ID as it appears in the RIPE Database
country	String	two letter country code as of ISO 3166-1 alpha-2
name	String	name of the autonomous system number
urloptional	String	URL of your official website

PUT AS-Number

Update details of a customer

PUT /v1/internet/resouces/asn/{id}

{}

Parameter

field	type	description
id	String
description	String	used for organisation name or individuals realname and firstname.
streetoptional	String	street
streetnumberoptional	String	street number
zipcodeoptional	Number	Postal code
cityoptional	String	City
stateoptional	String	State
country	String	Countrycode based on ISO-3166-1A2
telephonenumberoptional	String	phone number
mobileoptional	String	mobile number
vatidoptional	String	vat identifier

Internet/resources/ipv4

GET Pricing

List of all available ipv4 ranges

GET /v1/internet/resources/ipv4/available

[]

Internet/tunnel/layer2

POST L2 Create

Create new Layer2-Tunnel to get connected to an internet exchange point. These tunnels have no internet access, they are only connected to the internet exchange peering lan.

POST /v1/internet/tunnel/layer2

{}

Parameter

field	type	description
type	String	vxlan,gretap
endpoint	String	public remote ipv4 or ipv6 address
exchange	Number	internet exchange id

Tools/media/movie

GET Poster

Returns the cover image of a movie

GET /v1/tools/media/movie/{name}

{
    "adult": false,
    "backdrop_path": "\/vL5LR6WdxWPjLPFRLe133jXWsh5.jpg",
    "genre_ids": [
        28,
        12,
        14,
        878
    ],
    "id": 19995,
    "original_language": "en",
    "original_title": "Avatar",
    "overview": "In the 22nd century, a paraplegic Marine is dispatched to the moon Pandora on a unique mission, but becomes torn between following orders and protecting an alien civilization.",
    "popularity": 124.836,
    "poster_path": "\/kyeqWdyUXW608qlYkRqosgbbJyK.jpg",
    "release_date": "2009-12-15",
    "title": "Avatar",
    "video": false,
    "vote_average": 7.581,
    "vote_count": 30747
}

Parameter

field	type	description	value
name	String

GET Poster

Returns the cover image of a movie

GET /v1/tools/media/movie/poster/{name}

"https:\/\/image.tmdb.org\/t\/p\/w342\/kyeqWdyUXW608qlYkRqosgbbJyK.jpg"

Parameter

field	type	description	value
name	String

Tools/network/ssh

GET Ssh

Connect to specified host via ssh and return ip details, connection status and fingerprint

GET /v1/tools/network/ssh/{host}

{
    "as": 58057,
    "country": "CH",
    "isp": "Securebit AG",
    "ip": "193.33.95.1",
    "connection": true,
    "fingerprint": "4B42D4824B425C7A4B42D350935840DD"
}

Parameter

field	type	description	value
host	String

Company name

Overview

Introduction

Methods

Errors

Status Codes

Error Codes

Rate Limiting

Authentication

API-Key

Customer

Parameter

Parameter

Parameter

Parameter

Customer/group

Parameter

Parameter

Parameter

Parameter

Parameter

Customer/suffix

Parameter

Parameter

Parameter

Customer/user

Parameter

Parameter

Parameter

Parameter

Parameter

Internet/abuse

Parameter

Internet/abuse/report

Parameter

Internet/domain_name_system/zone

Parameter

Parameter

Parameter

Internet/exchange

Internet/exchange/connection

Parameter

Parameter

Internet/resources/autonomous_system

Parameter

Parameter

Parameter

Internet/resources/ipv4

Internet/tunnel/layer2

Parameter

Tools/media/movie

Parameter

Parameter

Tools/network/ssh

Parameter