TransIP makes domain and VPS services available via a REST API. By using your own scripts, your website, application, or server sends a request directly to the TransIP systems.
In this tutorial, we explain how to get started with the TransIP API: How do you generate a Key Pair for the API and what is that for? Next, we elaborate more on the API in the following articles:
- REST-API CLI-client: With the Command-Line-Interface client, you can easily call the API, for example, via shell scripts.
- The REST-API automatic authentication in PHP: How do you authenticate yourself automatically via PHP? Where can you find functions and entities in the PHP library?
- REST API PHP-examples: In this article, we provide some simple examples of how to use the PHP library and refer to some tutorials that explain more advanced API applications in PHP.
Are you an experienced programmer and do you want to jump straight into the action? Skip ahead to one of the following pages:
- 1000 API requests can be used per 15 minutes per TransIP account.
- Do you want to share your REST-API implementation with other customers? Send us a link to your Github repo through developers.transip.eu and you'll make a chance of having your implementation featured in our monthly community highlight.
- For using the TransIP API and developing your application, we recommend using an IDE. In this article we explain how using an API makes using our API easier.
Enabling the API, access and whitelisting
First, enable the TransIP API from your own TransIP account. To do this, go to the TransIP control panel, click the profile icon at the top right, followed by 'My account'> 'Api', or use this direct link.
First, enable the API settings on the API page by setting the slider next to 'Status' to 'On'.
The API page is further composed of three components that we explain below.
With every request that your website / application executes via the TransIP API, authentication takes place via access tokens that you send in a header. You can generate these tokens in two ways: automatically by downloading the authentication class, or manually with an expiration date in your control panel. For both, you can remove the tokens in your control panel.
When manually creating access tokens you specify the following options:
- Label: Gives a name to the access token.
- Expires in: Choose after how much time the access token expires. After this time, for example, after 24 hours, the access token is no longer usable. This is a security measure whereby, if the access token falls into the hands of third parties, it cannot be used for long.
- Whitelisted IP: Enable this option to allow only whitelisted IP addresses to use the access token. Uncheck to allow the access token to be used from any IP address.
- Read-only: With read-only, you can only retrieve data, such as a list of VPSs or domains, but not perform operations such as ordering or canceling a VPS or domain.
To automatically generate access tokens, you use a Key Pair. This consists of a Public Key, a Private Key, and a label. After adding a Key Pair, the Private Key is shown once. This Private Key can be used to automatically generate access tokens.
If you want to use a Key Pair, the IP address from which the request originates must be added to the whitelist. Note that a whitelist IP can be used for all Key Pairs that use whitelisting. Another option is to create a Key Pair that can be used from any IP address. To do this, uncheck 'whitelisted IP'.
The whitelist IP address is a list of trusted IP addresses that are allowed to execute API requests for your TransIP account.
Suppose you have a VPS which makes API calls with IPv4 address 18.104.22.168, then enter it in the 'IP address' field and click 'Add IP address'.
Whitelisting supports IPv4 and IPv6 addresses. In addition, you can also record entire IP ranges by specifying the range, for example: 22.214.171.124/24 or 2a01:7c8:aaaa:a::/64.
Generating a key pair
In the steps below, we show how you can authenticate yourself and set up a connection with the TransIP API.
Go to the API page in the TransIP control panel and add a Key Pair.
- Label: Give the Key Pair a label / name with which you can easily see what the Key Pair is used for, for example, the name of the server / domain from which you will use the API.
- Whitelisted IP: Leave this option on.
You will see a confirmation 'Key Pair successfully added' with the Private Key below. Make sure you store the private key securely and don't share it with others.
Whitelist the IP address(es) of the server from which you host your website / application.
This brings us to the end of this article about enabling the API and the associated options in the TransIP control panel.
Should you have any questions left regarding this article, do not hesitate to contact our support department. You can reach them via the ‘ContactUs’ button at the bottom of this page.
If you want to discuss this article with other users, please leave a message under 'Comments'.