This document describes how to get started with the Pix4D Cloud REST API, which provides third party applications access to Pix4D cloud service. It allows the client to upload images, launch the processing of projects and get the results back.
- The protocol used is HTTPS.
- The base URL for API endpoints is:
https://cloud.pix4d.com. - The REST API identifies Pix4D applications and users using OAuth2 (Bearer token).
- All the responses are available in JSON.
To register the application and start using the REST API please contact us at sales@pix4d.com.
Authentication
Equipped with the Pix4D API access key, the first step is to retrieve an authentication token.
Pix4D Cloud REST API uses OAuth 2.0, the industry standard for connecting apps and accounts.
The general OAuth2 concept is:
- The API client gets a token that gives him access to a user account
- In every single API call made, this token is passed as a header:
Authorization: Bearer <ACCESS_TOKEN>
The token will be valid for the number of seconds specified in the expires_in key of the authentication response. Before the access_token expires, it is possible to use the refresh_token to renew it. Otherwise after it expires the authentication procedure needs to be repeated.
Client Credentials flow
This is the one used by most users. Using this, API clients can get access to their own Pix4D account (and only to that account).
The client must send a request to obtain an access token. Here is an example curl request and response:
curl -X POST -d "grant_type=client_credentials&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>" https://cloud.pix4d.com/oauth2/token/
Response:
{"access_token": "<ACCESS_TOKEN>", "token_type": "Bearer", "expires_in": 36000, "refresh_token": "<REFRESH_TOKEN>", "scope": "read write"}
where
- url:
https://cloud.pix4d.com/oauth2/token/ - CLIENT_ID and CLIENT_SECRET are the credentials provided once the application is registered with Pix4D
- grant_type: client_credentials
- expires_in is expressed in seconds and specifies the lifetime of access_token
For the use of the refresh_token, see below.
Password flow
This procedure gives access to another user's resources (and therefore requires this user's username and password).
To authenticate a user in the system and get the access token that gives access to the user resources, a request needs to sent as described below:
- url:
https://cloud.pix4d.com/oauth2/token/ - CLIENT_ID and CLIENT_SECRET are API client credentials provided when the application is registered with Pix4D
- grant_type: password
- USERNAME and PASSWORD are the final user's credentials
A curl request example:
curl -X POST -d "grant_type=password&username=<USERNAME>&password=<PASSWORD>" -u"<CLIENT_ID>:<CLIENT_SECRET>" https://cloud.pix4d.com/oauth2/token/
Response:
{"access_token": "<ACCESS_TOKEN>", "token_type": "Bearer", "expires_in": 36000, "refresh_token": "<REFRESH_TOKEN>", "scope": "read write"}
Using the refresh token
The refresh token allows the API user to obtain a new token if the current one has not yet expired. Here is an example:
Request:
curl -X POST -d "grant_type=refresh_token&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&refresh_token=<REFRESH_TOKEN>" https://cloud.pix4d.com/oauth2/token/
Response:
{"access_token": "<ACCESS_TOKEN>", "token_type": "Bearer", "expires_in": 36000, "refresh_token": "<REFRESH_TOKEN>", "scope": "read write"}
Processing
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 API access.