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.
Accessing to APIs resources is a two steps process (based on the open specification OAuth 2 client credentials grant (opens new window)):
- Request a JSON Web Token (JWT) with your
client_id
andclient_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"
}'
2
3
4
5
6
7
8
9
10
- Send your authenticated request to the API endpoint using the
access_token
part of the freshly generated JWT token. Provide theaccess_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}}"
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"
2
3
4
5
Info
It is recommended to always have this header set so all APIs are called similarly.