Authentication and authorization

Introduction

The Nitrobox REST API uses 2-legged OAuth, which is part of the OAuth 2.0 specification - the industry-standard protocol for authorization.

To access the API endpoints the following flow needs to be implemented:

  1. authenticate via HTTP Basic Authentication, providing your credentials, to obtain an access token
  2. subsequently use the access token to authorize every request to the API itself

👍

Any URLs needed to access the Nitrobox API, will be provided to you in the onboarding process by your dedicated contact person.

Credentials can be managed within the webportal, given the user has the required role to manage them.
Your initial admin account will have the required "Manage api credentials" role

Authentication to obtain an access token

The URL to aquire the access token is

https://api.{your Nitrobox SaaS instance}/{realm}/oauth2/token?grant_type=client_credentials.

In the request to this URL you need to provide the HTTP header 'Authorization' which contains the authorization method and a space ("Basic ") appended by a Base64-encoded string of the scheme client_id:client_secret. Check the following sample for a better understanding:

Concatenated client id and secret | my_client_id:my_client_secret
Base64 encoded string             | bXlfY2xpZW50X2lkOm15X2NsaWVudF9zZWNyZXQ=
HTTP Header in POST request       | Authorization: Basic bXlfY2xpZW50X2lkOm15X2NsaWVudF9zZWNyZXQ=

Following a simple cURL example on how this request could look like and the response to this:

curl --location --request POST 'https://api.{your Nitrobox SaaS instance}/{realm}/oauth2/token?grant_type=client_credentials' \
--header 'Authorization: Basic {your base64 encoded client_id:client_secret}'
{
    "access_token": "{your access token is returned here}",
    "token_type": "bearer",
    "expires_in": 269
}

👍

Reusing the access token improves performance!

The access token is valid for a certain amount of time (depending on the security config on your instance, default 5 minutes) and can be reused as often as you like in this time. Requesting a new access token for each request can slow down performance considerably and is neither necessary nor recommended.

Authorize every API call providing the access token

For every request to the API the access token must be provided to authorize the call for the requested resource, again using the HTTP header 'Authorization':

curl --location --request GET 'https://api.{your Nitrobox SaaS instance}/some-resource \
--header 'Authorization: Bearer <your access token>'