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 resource
  • POST Creates a new resource
  • PATCH Applies partial modifications to a resource
  • PUT Replaces an existing resource
  • DELETE 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 a POST request with either:

  • an X-HTTP-METHOD-OVERRIDE header equal to DELETE
  • or a _method parameter equal to DELETE

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:

CodeShortDescription
200OKThe request is successful
201CreatedThe request is complete, and a new resource is created
401UnauthorisedThe requested URI needs the client to have an API token with the right scopes (see OAuth2 below)
403ForbiddenAccess is forbidden to the requested resource
404Not FoundThe server can not find the requested resource
422Unprocessable EntityThe request was well formatted, but the request content contains semantic errors
500Internal Server ErrorThe 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.CodeDescription
11xx: InformationalThe request has been received and the process is ongoing
22xx: SuccessThe action was successfully received, understood, and accepted
33xx: RedirectionFurther action must be taken in order to complete the request
44xx: Client ErrorThe request contains incorrect syntax or cannot be fulfilled
55xx: Server ErrorThe server failed to fulfil an apparently valid request

More info

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 default order 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 return
  • skip 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 number
  • per_page integer: number of element per page

Additional values

These values are added to the response root

  • total integer: total number of elements
  • page integer: current page number
  • pages integer: total number of pages
  • items_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.

  1. Add a new operation:

    New request
  2. Create a new basic request:

    Create new basic request
  3. Save the new request:

    Save 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.

  4. Specify which HTTP request you want to use:

    Select HTTP method

    Select the method you want to use in the list according to the operation you want to perform on the chosen route.

  5. Add your authentication credentials:

    Add bearer
    1. Start by specifying the route you want to use
    2. Click on the authorisation menu
    3. Select the type of authorisation as Bearer Token
    4. Enter your token in the field
    5. Click on Send
    6. Visualise the response payload