Pix4Dengine Cloud authentication procedure – Support

This document describes how to get started with the Pix4D Cloud REST API, which provides third party applications access to thePix4D Cloud service. It allows a Pix4D Engine Cloud client to access his/her data on the cloud and perform a range of operations on them.

For end to end security, HTTPS is used in all the APIs
The base URL for API endpoints is: https://cloud.pix4d.com
Each REST API call needs to be authenticated. See Authentication below
The communication format is expected to be JSON, unless otherwise stated

Getting access to Pix4D Cloud REST API

To register the application and start using the REST API you will need to acquire a Pix4D Engine Cloud license. Please contact us at Salesteam (at) pix4d.com and we'll help you get set up and will give you a pair of client_id/client_secret that represent your application, the one that will connect to the Pix4D API and that you will use to authenticate to the API.

Note that as its name suggests, client_secret is a password identifying the client application and therefore should be handle securely.

API Authentication

Equipped with the Pix4D API client_id/client_secret, the first step is to retrieve an authentication token. An authentication token identifies both the application connecting to the API and the Pix4D user this application is connecting on behalf of.

This token must then be passed along every single request that the application makes to the Pix4D API. It is passed in the HTTP Authorization header, like so:

Authorization: Bearer <ACCESS_TOKEN>

Pix4D Cloud REST API uses OAuth 2.0, the industry standard for connecting apps and accounts. OAuth 2.0 supports several "authentication flows" to retrieve an authentication token. Pix4D supports several of them that are each used for a specific purpose, but for Pix4D Engine Cloud customers, only one is relevant: "Client Credentials"

Client Credentials flow

Using this flow, an API client application can get access to its own Pix4D user account (and only to that account). With this method, the authentication is straightforward and only requires the applications' client_id/client_secret pair

The client must send the following HTTP POST request to https://cloud.pix4d.com/oauth2/token/ with a payload containing:

grant_type: client_credentials
client_id: the client ID of the application that was given to you by your Pix4D contact
client_secret: the client_secret of the application that was given to you by your Pix4D contact
token_format: jwt

example:

curl -X POST \
  -d "grant_type=client_credentials&token_format=jwt&client_id=YuB7fu…&client_secret=GMSVvt8dF…" \
  https://cloud.pix4d.com/oauth2/token/

Token information

Token content

The response you receive when performing the authentication request above has the following content (In JSON):

access_token: the token value that you will have to join in all your requests
token_type: for Pix4D, this is always a Bearer token
expires_in: the number of seconds the token is valid for. After this number of seconds, API requests using this token will get rejected and you will need to request a new token through the authentication procedure again
scope: describe what the token is valid for. In this case, it's always "read write" since you get a full access to your own account

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 36000,
  "scope": "read write"
}

Refreshing the token

When the token expires, you simply need to perform the above authentication procedure again to get a fresh token.

Using the API

For an in-depth description of all possible API commands, please refer to the API documentation. This documentation is only available for users who already have an API access.