REST APIs

• 1: Base URL & service user
• 2: Rate limiting
• 3: Authentication API
• 4: Client account API
• 4.1: Getting started
• 4.2: API reference

1 - Base URL & service user

To get started with the integration, you need the following information:

• Base URL: the URL where all API endpoints are located for your platform instance
• Service user: the account set up for your platform instance to fetch the authentication token for the API endpoints

Base URL

As a customer, you have a staging and production environment:

• Staging base URL: https://api.staging.<platform_id>.platform.io
• Production base URL: https://api.<platform_id>.platform.io

Your platform_id is provided to you during your onboarding.

Service user

The service user consists of a user name and password, which is provided to you by your account manager.

2 - Rate limiting

Each endpoint in the platform's REST API can be called up to 300 times per minute. Deviations to this rate limit are indicated on the affected endpoints.

3 - Authentication API

Bearer token

An API token is used to authenticate with all endpoints, except the Authentication API, where the API token is fetched from. Use your service account details to fetch the API token.

This API token is used as a Bearer token in the header of each API call.

Headers:
  Authorization: Bearer <api-token>

API token payload and expiry

The API token returned from this API endpoint is a JSON Web Token (JWT) and contains an expiry time. This means that you are required to fetch a new API token when the previous one has expired before making calls to other endpoints which require an API token for authentication.

The expiry time can be read from the token’s payload part, in the exp property.

Example payload of a token:

{
  "r": [
    "service"
  ],
  "exp": 1642159394,
  "sub": "f76ec415-1811-4935-a659-63dc2483c852",
  "reg": "za"
}

For more information on JWT and decoding the token, refer to jwt.io.

API reference

Try out fetching an API token for your staging environment.

4 - Client account API

The client account API is used when your clients sign up or log in to your platform instance through your web application. This API enables you to create, edit and delete client accounts and create sessions for the client when they log in.

4.1 - Getting started

Build the base URL

Use your platform_id to build up the base URL for all available REST API endpoints. See Base URL for more information.

For example, if your platform_id is my_company_platform_id, then the base URL for the REST API endpoints in your staging environment is https://api.staging.my_company_platform_id.platform.io.

Fetch API token

Before calling the client account API endpoints, fetch an API token with your service user using the Authentication API endpoint.

For example, if your service user for your staging environment has the following login details:

• username: service_user
• password: xxxyyy

, then the call looks as follows:

curl POST https://api.staging.my_company_platform_id.platform.io/v1/login/password \
--data '{
    "username": "service_user",
    "password": "xxxyyy"
}'

, with a success response as follows:

{
    "api_token": "your_api_token"
}

Create a client account

Use the newly created API token as a bearer token in the header for each call to the client account API endpoints. For example, when you create a new client account. See Create client account for more information.

Example call:

curl POST https://api.staging.my_company_platform_id.platform.io/v1/client/signup \
--header 'Authorization: Bearer your_api_token' \
--data '{
    "user_id": "80491f93-1eb1-42c2-b5e1-d2e94dac5ab9",
    "email": "new_client@client.com",
    "name": {
        "first_name": "new",
        "last_name": "client"
    },
    "password": "new_client"
}'

Response:

{
    "client_token": "client_token"
}

4.2 - API reference

Try out the client account API on your staging environment.