Authentication

Stenn API uses your client_id and client_secret server side keys to control access to our API via the Client Credentials Flow (defined in OAuth 2.0 RFC 6749, section 4.4) which exchanges your client credentials for an access token.

How it works

Your application sends client_id and client_secret to our API.

curl --request POST \
  --url 'https://{base_url}/v1/auth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET

Note that the version number is not required in the authentication URL.

Upon receiving your credentials, Stenn API will validates your app credentials and respond with an access token.

{
  "access_token":"eyJz93a...k4laUWw",
  "token_type":"Bearer",
  "expires_in":86400
}

Your application can now use the access token to call any of our available API endpoints and respond with your requested data.

curl --request GET \
  --url 'https://{base_url}/v1/companies' \
  --header 'authorization: Bearer {ACCESS_TOKEN}' \
  --header 'content-type: application/json'

Access token expiration

Our API provides an access token upon a successful authentication request. With this access token, you can make authenticated requests to our API endpoints. However, these access tokens have an expiration date that enhances security by limiting the token's lifespan for up to 20 hours. Once expired, you will need to re-authenticate to request for a new access token. Using an expired access token to make API requests will return a 401 error code with an error message indicating that the access token has expired.

Here’s how you can request for a new access token after it has expired:

curl --request POST \
  --url 'https://{base_url}/v1/auth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET

📘

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.