Authentication and authorization


Authentication and authorization

The documentation explains how you can use Skalin APIs safely.

# Security concerns

Skalin APIs offer a powerful way to manage mass data assets that could be sensitive (PII). This is the reason why security is an important concern regarding APIs usage.

APIs security is ensured by state-of-the-art harding practices like:

  • Data encryption at rest and in transit
  • Flow monitoring, automated alerts and an on-call team
  • Payloads and headers scanning (against OWASP TOP 10 (opens new window) attacks patterns)
  • Requests tracing and persisted access logging
  • Requests rate limiting
  • OAuth 2 / OIDC based identity and access management
  • And further more...

The next sections will detail authentication, authorization and requests rate limiting processes.

# How to get a credentials bundle

Before users can make requests with APIs, they'll need to register for an API key (credentials bundle) and learn ways to authenticate the requests.

To create this key, please refer to the integration documentation Creating an API key. Each credentials bundle contains a client_id and a client_secret, which must be kept strictly confidential.

Each credentials bundle is linked to an owner responsible of its distribution to authorized developers. The owner is also is accountable of credentials protection (avoid leaks, request a secret rotation, request secret invalidation, etc.). The bundle requester is considered as owner by default.

It could be useful to have multiple credentials bundles: each credentials bundle is associated with a single use case. In fact if one use case security is compromised, it is easy to rotate the associated secret locally without having to change the configuration of all applications consuming the APIs.

Permissions associated with the credentials bundle could be restricted to specific api resources or scopes. Default credentials bundle associated permissions are the same as the owner's ones. Permission restriction requests should be addressed to the support.

# How to authenticate requests

Overall, authentication and authorization with APIs serves the following purposes:

  • Authenticate calls to the API to registered users only
  • Track who is making the requests
  • Track usage of the API
  • Block or throttle any requester who exceeds the rate limits
  • Apply different permission levels to different users

The diagram bellow explains the way to authenticate requests.

Skalin oauth flowchart

Accessing to APIs resources is a two steps process (based on the open specification OAuth 2 client credentials grant (opens new window)):

  1. Request a JSON Web Token (JWT) with your client_id and client_secret to the authentication server (auth.skalin.io)
# curl authentication example
curl --location \
--request POST 'https://auth.skalin.io/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "client_id":"{{TokenClientId}}",
    "client_secret":"{{TokenSecret}}",
    "audience":"https://api.skalin.io/",
    "grant_type":"client_credentials"
}'
1
2
3
4
5
6
7
8
9
10
  1. Send your authenticated request to the API endpoint using the access_token part of the freshly generated JWT token. Provide the access_token as a request authorization header (bearer):
# curl api request example
curl --request POST https://api.skalin.io/v1/customers?clientId={{clientId}} \
--header "Content-Type: application/json" \
--header "Authorization: Bearer {{AccessToken}}"
1
2
3
4

Info

Access tokens not only provide authentication for the requester but also define the permissions of how the user can use the API. Additionally, access tokens expire after a period of 6 hours and require to reiterate the first step.

# How to deal with rate limits

Each endpoint is protected by a request rate limit to prevent APIs service outage. When clients exceed this limit an HTTP error 503 is returned by our servers. It's a common way to protect a service against abusive usage, bugged scripts or denial-of-service attack (DoS).

Find below the detail of rate limits per endpoint:

# Authentication endpoint rate limits

The number of requests per seconds accepted from a given IP on auth.skalin.io endpoint is:

  • Nominal rate limit: 5 rqps
  • Burst rate limit: 10 rqps

Warning

You have to save current access token and refresh it only when it expire. Each access token have a life period of 6 hours. Maximum generated access token by day is 15.

# API endpoint rate limits

The number of requests per seconds accepted from a given IP on api.skalin.io endpoint is:

  • Nominal rate limit: 20 rqps
  • Burst rate limit: 35 rqps

# Response language

Some endpoints support a language selection, such is the case of the API used for listing data schemas because of the field label. For these APIs you should add an Accept-Language header to request the appropriate language.

The languages supported for now are fr and en, the latter being the default value.

# curl api request example
curl --request POST https://api.skalin.io/v1/customers?clientId={{clientId}} \
--header "Content-Type: application/json" \
--header "Authorization: Bearer {{AccessToken}}" \
--header "Accept-Language: fr"
1
2
3
4
5

Info

It is recommended to always have this header set so all APIs are called similarly.

Contributors: Julien