Authentication

The Sikoia API is secured using the OAuth 2.0 protocol. Sikoia authenticates your requests using an access token, and if a request doesn't include a valid access token, Sikoia returns an Invalid authorization response. To obtain an access token make a request to the Access Token endpoint providing your client ID and client secret (client credentials grant).

Your client ID will be assigned to your account when it is created. You will need to generate your client secret and periodically rotate this. Your client ID and client secret are specific to an environment.

You can create new secrets, and view and manage existing ones via the Sikoia Dashboard under the Applications menu option. If you do not have access to the Dashboard, please reach out to Sikoia Customer Support using the support button.

ℹ️

For customers that went live pre January 2024, we will continue to support API keys for a transitionary period

Click here to read more about how we plan to continue to support you securely during this transition.

Generate Your Client Secret

In order to interact with the Sikoia API you will need to fetch your client ID and generate a client secret via the Sikoia Dashboard.

To do this, open the Sikoia Dashboard, select the applications menu option and follow the steps below:

1. Select “New Secret”
2. Give your secret a helpful name and select “Create”
3. Save the Client Secret visible on screen

⚠️

The client secret value will only be visible once at this point

It is very important you record this securely as Sikoia will not be able to retrieve it for you at a later date.

If you forget your client secret, you will need to create a new one following the process outlined above.

You will have a different application per environment so make sure to record the correct client ID and associated secret for each environment securely.

Rotate & Revoke Client Secrets

By default, all client secrets will expire two years after issuance. You are able and advised to rotate your client security more frequently via the Sikoia Dashboard.

Sikoia offers the ability to have two secrets per application to enable you to rotate the secrets without restricting access. The expiry date of each secret is available to view in the Dashboard.

Ahead of the secret expiry date a second secret should be generated using the steps above. Ensure you securely capture the new secret and update your integration with Sikoia to use this new secret.

Once this has been done successfully, you can revoke the old secret.

Create Your Access Token

Once you’ve retrieved your client ID and securely recorded and stored your client secret, you can retrieve your access token by making a request as per below:

curl -X POST 'https://oauth2.sikoia.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'scope=https://api.sikoia.com/.default' \
-d 'client_id=<<client_id>>' \
-d 'client_secret=<<client_secret>>'

View the POST Access Token endpoint.

All requests made to the Sikoia API will need to include an access token in the Authorization header of the request:

Authorization: Bearer {access_token}

Sikoia access tokens have a 1-hour expiry. After expiration, you will be required to generate a new token with the same mechanism.