Authentication

This part of the documentation shows you how to authenticate with the sellytics DATA API. The DATA API makes use of the OAuth2 client_credentials flow with Bearer Tokens. This grant-type was not made to be used in client-side applications since you shouldn't ever expose your client-secret to the public world. So if you want to show some data in a client-side application create at least an upstream proxy with your own authentication or protection. You can read more about the client_credentials grant type here.

Get API Credentials (API Key)#

To get your own sellytics DATA API credentials login to the sellytics-suite with your sellytics account. Choose your space where for which you want to create API credentials and go to the DATA API module. Use the "Create new key"-Feature in the API Keys section to create new API credentials. You can optionally add a label to your credentials to know for what or which project you've created the key.

Sellytics Suite DATA API Key Screenshot

warning

API keys cannot be recovered - so store them carefully!

Get a Bearer access_token#

To make API calls / requests to the sellytics DATA API you always have to send a Bearer (Auth) Token in every request header. You can obtain the bearer token using client_credentials OAuth2 grant type from our token-endpoint.

PropertyValue
Token endpointhttps://auth.sellytics.com/auth/realms/sellytics/protocol/openid-connect/token
Scopesellytics-data-api

Using the access_token#

Example request using curl to get the access_token, using the client_credentials grant type:

curl -X POST 'https://auth.sellytics.com/auth/realms/sellytics/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<your-client-id>' \
--data-urlencode 'client_secret=<your-client-secret>' \
--data-urlencode 'scope=sellytics-data-api' \
--data-urlencode 'grant_type=client_credentials'

When the request was successful you should get a response json payload with your Bearer access_token.

{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSjy_rhgRG_3EQyKZswYnEFHzS4v ...",
"expires_in": 86400,
"refresh_expires_in": 86400,
"refresh_token": "eyJhbGciOiJIUzI1NiIWFsbXMvc2VsbHl0aWNzIiwic3ViIjoiN...",
"token_type": "bearer",
"not-before-policy": 0,
"session_state": "7df5b4cb-00bf-4a6e-90f4-1c8a1863c135",
"scope": "sellytics-data-api"
}

You can use this access_token now to make authenticated requests against the sellytics DATA API.

We don't recommend using refresh_token in DATA API context#

Since the sellytics DATA API is using client_credentials OAuth2 grant which is designed for server-side clients and access where the client_id and client_secret aren't visible to the public world you don't need to use the refresh_token grant and feature. The issuance of a refresh token with the client_credentials grant has no benefit. That is what the RFC6749 section 4.4.3 indicates but many authorization servers including ours do not respect. So it is enough to just re-authenticate when the access_token is expired with the client_credentials grant as described in the paragraph above.