Getting Started

Authentication

The Mapiq API supports application-level access to your Mapiq data using the OAuth 2.0 Client Credentials grant flow. To retrieve a token using the Client Credentials grant flow, you will need a client application.

Requesting client applications

Creating and managing client applications is currently not yet available as a self-service experience. Please contact Mapiq support with creation or change requests to client applications for the Mapiq API.

To create a new client application, send a request to Mapiq support with the following information:

1. The display name for the client application.

2. The display name for the credential of the new application.

3. The required Mapiq API permissions for the client application.

4. A short description of the intended use of this Mapiq API client application.

Mapiq support will verify your request and once validated, provide you with the client id and client secret that you can use to obtain tokens.

Use your client application to request an access token

Route

POST https://account.mapiq.com/api/public/oauth2/token

Required headers

• content-type

  • Required, always: application/x-www-form-urlencoded

Request form parameters

• grant_type

  • Required, always: client_credentials

• scope

  • Required, always: https://api.mapiq.com/public/.default

• client_id

  • Required, the id of your Mapiq API client application (provided by Mapiq)

• client_secret

  • Required, the secret of your Mapiq API client application (provided by Mapiq)

Response

After you have successfully retrieved a token from the endpoint., you can use the access_token to authenticate yourself against the public API. The token has the following properties:

• access_token

  • The access token for authenticating to the Mapiq API.

• token_type

  • The type of the token, always Bearer.

• not_before

  • The time from which the access token is usable. Date represented as the number of seconds since Unix epoch.

• expires_in

  • The amount of time in seconds that the access token is valid.

• expires_on

  • The time when the access token expires. Date represented as the number of seconds since Unix epoch.

• resource

  • The Mapiq API

Example request

An example request for retrieving an access token for the Mapiq API with the 'client_id' being '11111111-0000-0000-0000-000000000000' and the 'client_secret' being '1qfyWaaSgG...'

POST /api/public/oauth2/token
Host: https://account.mapiq.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=https%3A%2F%2Fapi.mapiq.com%2Fpublic%2F.default&client_id=11111111-0000-0000-0000-000000000000&client_secret=1qfyWaaSgG...

The associated curl command for the example request:

curl --request POST \
  --url https://account.mapiq.com/api/public/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data scope=https://api.mapiq.com/public/.default \
  --data client_id=11111111-0000-0000-0000-000000000000 \
  --data client_secret=1qfyWaaSgG...

Use the access token

The resulting JWT Bearer token can now be used to authenticate requests you make to our API. To send a request with the Bearer Token authorization header, you need to make an HTTP request and provide your Bearer Token in the "Authorization: Bearer {token}" HTTP header.

Rate limiting

Our API has rate limiting configured. By default, the Mapiq API will allow up to 20 requests per minute per endpoint, but some endpoint can deviate from this. If you exceed the rate limit, our API will start rejecting your requests with a HTTP status 429 (Too Many Requests).

{
   "statusCode" : 429,
   "message": "Rate limit is exceeded. Try again in 289 seconds."
}

API Reference

Go to the API Reference page to find out which endpoints are available and on how to use them.