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

Domains

We currently support two default domains, one for testing purposes and one for production.

Authentication to obtain an access token

The URL to acquire the access token is

https://api.nitrobox.io/{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 how this request could look like and the response to it:

curl --location --request POST 'https://api.nitrobox.io/{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
}

👍

Access token should be cached and reused until expiry to improve performance!

The access token is valid for a certain amount of time (depending on the security config on your instance, default is 5 minutes) and should be reused for consecutive requests until expiry.

Requesting a new access token for each and every API request will considerably slow down performance and is bad practice in general.

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.nitrobox.io/some-resource \
--header 'Authorization: Bearer <your access token>'