API Usage

OAuth 2.0 is an open standard for securely authorizing access to protected resources. It allows applications to access data or services on behalf of a user without requiring the user’s username and password to be shared.

Instead, the application receives time-limited and scope-limited access tokens that precisely define what it is allowed to do and for how long. OAuth 2.0 clearly separates the roles of the user, client application, authorization server, and resource server, thereby providing greater security, flexibility, and control.

Prerequisites

Before OAuth 2.0 can be used, the application must be registered with the authorization server.
During this process, the client receives a client ID for unique identification as well as a client secret, which is used to authenticate the application. In addition, a scope is defined that specifies which resources and functions the application is allowed to access. These details are required to ensure that the authorization process is carried out securely and in a controlled manner.

Separate client IDs and access tokens must be requested for each environment — sandbox, testing, and production. The environments are technically and security-wise isolated from each other, meaning that credentials and tokens must not be used across environments. This ensures that tests have no impact on production data and that each environment is clearly separated and controlled.

You can obtain the required client ID and secret via the customer portal.

Requesting an Access Token

Assuming that you have requested and received the client ID and secret via the portal, you can now request an access token.
Below you can see an example curl command. In practice, you should of course use the technology stack of your own IT application.

# Example for generating an access token for the testing environment
curl -X POST https://hydra.nxtlabs.online/oauth2/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "scope=thg-testing" \
     -u a43e4908-5839-4421-aa81-76672c85b400:S~MddeCBr~U1aPxWOC4s0~HSQY
# Analogous for sandbox (thg-sandbox) and production (thg-production)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImJlNWY4YzcwLTQ4ZjMtNGU1NS1iMDZkLThjYzRjMmU3YWFjNiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86399,
  "scope": "thg-testing",
  "token_type": "bearer"
}

Notes:

• The response shown above is only an example of an access token. The response to your own request will of course look different, but it will still be a valid JSON Web Token (JWT).
• The access token is only valid for a limited period of time and must therefore be renewed regularly (daily) using the routine described above.
• If required, you can inspect the contents of the generated access token, for example by using the website JWT IO.

// Example: Decoded access token
{
  "aud": [],
  "client_id": "a43e4908-5839-4421-aa81-76672c85b400",
  "exp": 1770716236,
  "ext": {},
  "iat": 1770629836,
  "iss": "https://hydra.nxtlabs.online",
  "jti": "03a3f792-a9b5-4f39-aac6-d8e5dc88f89d",
  "nbf": 1770629836,
  "scp": [
    "thg-testing"
  ],
  "sub": "a43e4908-5839-4421-aa81-76672c85b400"
}

Note: The JSON Web Key Set (JWKS) is available at https://hydra.nxtlabs.online/.well-known/jwks.json You can use it to verify the generated access token (JWT) yourself.

Sending a Request

Using the returned access token, you can now make requests to the API by including the token (the string in the access_token field) as a Bearer token in the Authorization header.

Below is an example request to the /api/v1/whoami endpoint.

curl -v https://thg.nxtlabs.online/api/v1/whoami \
     -H "Authorization: Bearer <access_token>"
# Replace <access_token> with the access token generated for you.

{
  "identity": "b2466469-825f-4233-9122-c585d163daed",
  "roles": "user,thg-testing,oauth2"
}