Introduction
Develop your applications with Infomaniak
Propel your online activities by using independent, privacy-friendly technologies that are constantly evolving. Whether you want to store data, send emailing campaigns, broadcast media, order or administer Infomaniak products, our API allows you to exploit the full potential of the Infomaniak ecosystem in your own applications using your favourite languages.
The Infomaniak API is RESTful and uses the OAuth v2.0 protocol for authentication and authorisation purposes.
Usage examples
- Perform multiple tasks at once.
- Automate common tasks.
- Script mass actions and updates.
- Create your own managing interface.
The only limit is your creativity !
This API (Application Programming Interface) can be used to access some of our services and help you managing multiple tasks at once, automate them. It can also allow you to script massive actions like backups or updates. Finally you can create your own manager application internally.
API rules
- Rate limit: you are limited to 60 requests per minute on our API. Some URI can have an additional custom limit.
- Encoding: this API uses the HTTP RESTful format. The requests sent and responses received are always JSON encoded.
- URL format: the API's URL format is always the same:
/{version}/{command_path}
. The version can be skipped; in this case you will have a response from the latest version.
HTTP query format
The HTTP methods used are:
GET
Provides a read only access to a resourcePOST
Creates a new resourcePATCH
Applies partial modifications to a resourcePUT
Replaces an existing resourceDELETE
Deletes a resource
All requests but GET must have a JSON encoded body.
Warning: some HTTP / REST clients don't support providing a body with the
DELETE
method this can be a problem when sending sensitive data. To handle this case you can send aPOST
request with either:
- an
X-HTTP-METHOD-OVERRIDE
header equal toDELETE
- or a
_method
parameter equal toDELETE
HTTP response format
The responses will always be JSON encoded and their first field will always be result
. Then depending on the result of your request:
- Success: you will have a
data
field with the requested resource or the response to your request. - Error: you will have an
error
field which describe the error.
Our REST server simply provides access to resources and you access and modify the resources according to your permissions. Each resource is identified by URIs / global IDs. REST uses various representations to represent a resource such as text, JSON, XML. We use JSON.
Overall structure:
{
"result": "success"|"error",
"data": [returned data],
"error":
{
"code": string,
"description": string,
"context": {additional data},
"errors": [array of error messages],
[
{
"code": string,
"description": string,
"context": {},
}
]
}
}
Let's split it so it is easier to understand:
Success response:
{
"result": "success",
"data":
{
"id": 12,
"name": "John Doe"
}
}
Single error response:
{
"result": "error",
"error":
{
"code": "object_not_found",
"description": "Object not found"
}
}
Multiple errors response:
{
"result": "error",
"error":
{
"code": "validation_failed",
"description": "Validation failed",
"errors":
[
{
"code": "attribute_required",
"description": "The name attribute is required",
"context":
{
"attribute": "name"
}
},
{
"code": "attribute_min_value",
"description": "You must be at least 18 years old",
"context":
{
"attribute": "age",
"min_value": 18
}
}
]
}
}
HTTP response codes
In our API, you can encounter any codes but the most frequent are the following:
Code | Short | Description |
---|---|---|
200 | OK | The request is successful |
201 | Created | The request is complete, and a new resource is created |
401 | Unauthorised | The requested URI needs the client to have an API token with the right scopes (see OAuth2 below) |
403 | Forbidden | Access is forbidden to the requested resource |
404 | Not Found | The server can not find the requested resource |
422 | Unprocessable Entity | The request was well formatted, but the request content contains semantic errors |
500 | Internal Server Error | The request was not completed. The server met an unexpected condition |
The status-code element in a server response is a 3-digit integer where the first digit of the status-code defines the response class.
There are 5 possible values for the first digit:
S.N. | Code | Description |
---|---|---|
1 | 1xx: Informational | The request has been received and the process is ongoing |
2 | 2xx: Success | The action was successfully received, understood, and accepted |
3 | 3xx: Redirection | Further action must be taken in order to complete the request |
4 | 4xx: Client Error | The request contains incorrect syntax or cannot be fulfilled |
5 | 5xx: Server Error | The server failed to fulfil an apparently valid request |
Authentication and Authorisation
We use OAuth2 to grant you access to our API. You can create an access token in your Infomaniak manager: https://manager.infomaniak.com/v3/ng/accounts/token/list.
The token must then be provided in your request headers this way:
curl --location --request GET 'api.infomaniak.com/...' \
--header 'Authorization: Bearer YOUR-TOKEN-HERE'
OAuth2 is now widely used to authenticate an user. It has the particularity of associating scopes with a token which is not possible in basic authentication (user and password) or with an API key.
Hence the particularity of OAuth2 of managing the authentication part of a user as well as the authorisations which was not possible with conventional authentication methods.
To access a URL, your token must have the scopes required by this URL, and you must have enough permissions with regard to the resource requested.
Example: to access the GET route api.infomaniak.com/1/domains/account/{your_account}/domain/{your_domain}
, your token must have the domains
scope and you must be allowed to access the requested domain.
Applications
Infomaniak provide OAuth2.0 and OpenID Connect authentication to connect to your external services via your Infomaniak log-in.
You can create your applications in your infomaniak manager:
https://manager.infomaniak.com/v3/ng/accounts/applications/list.
Authorization Request URL
https://login.infomaniak.com/authorize
Token Request URL
https://login.infomaniak.com/token
You can find additional information about OAuth2 authentification here: https://aaronparecki.com/oauth-2-simplified
Common parameters
Some routes have particular capabilities that are listed in their description. These capabilities can be:
Order by
Allows you to sort the response results.
Parameters
order_by string|array
: sorting field. Array or string separated by commas.order string
: sorting direction,'asc'|'desc'
default:asc
.order_for object
: sorting order for a field. By defaultorder
will be used. Example:order_for[id]=asc
.
Offset
Allows you to limit the number for results of a request and define from which element you want the results.
Parameters
limit integer
: number of elements to returnskip integer
: index of the first element to return (0 = first element)
Paginate
Allows you to paginate the response results where you choose the number of results per page.
Parameters
page integer
: page numberper_page integer
: number of element per page
Additional values
These values are added to the response root
total integer
: total number of elementspage integer
: current page numberpages integer
: total number of pagesitems_per_page integer
: number of elements per page
Total
Allows you to display the total number of results instead of the result itself for your request.
Parameters
return 'total'
: indicates that you want the total number of results in the response and not the list of results.
Additional values
These values are added to the response root
total integer
: total number of elements
Tutorials
Make your first request using Curl
Example:
curl --location --request GET 'https://api.infomaniak.com/profile' \
--header 'Authorization: Bearer $YOUR-TOKEN'
More generally:
curl --location --request $HTTP-VERB 'https://api.infomaniak.com/$ROUTE-PATH' \
--header 'Authorization: Bearer $YOUR-TOKEN'
Make your first request using PostMan
You can use Postman to help you writing the requests.
Add a new operation:
Create a new basic request:
Save the new request:
First add a name to your request, then a description. Finally you will need to create a folder/collection in which you can add your request and save it.
Specify which HTTP request you want to use:
Select the method you want to use in the list according to the operation you want to perform on the chosen route.
Add your authentication credentials:
- Start by specifying the route you want to use
- Click on the authorisation menu
- Select the type of authorisation as
Bearer Token
- Enter your token in the field
- Click on
Send
- Visualise the response payload