Good practice: Using organizational tokens

🛠️ Good Practices
1

Organizational tokens are the preferred authentication method for any production application using the gridX API.
This post aims to de-mystify their usage and provide code snippets that demonstrate the best practices to handle them in production.

Organizational tokens vs personal tokens

Xenon supports two types of tokens that can be used to access the gridX API: organizational and personal.

  • Organizational tokens are meant to be used for backend-to-backend integrations. They are tied to a Xenon account and their permissions can be set as any subset of the account’s policy groups.
  • Personal tokens, as the name indicates, are intended for personal usage. They are a convenience tool for developers testing locally against the gridX API to avoid the hassle of constantly replacing their short-lived bearer tokens.
    The permissions of a personal token are always identical to those of the user that created it.

Creating an organizational token

To authenticate with the API, you will first need to copy your bearer token. A bearer token is a short-lived JSON Web Token (JWT for short) which is generated after you log into Xenon.
It serves as an API token for the duration of your browsing session.

  1. Log into the Xenon account you want to create an organizational token for. Head over to the User Settings tab and copy your bearer token by clicking on the copy icon as shown below:

Copy user's bearer token
Copy user's bearer token797×602 44.2 KB

Note: The authenticated user must be part of a policy group with the AccountTokenWrite permission for the token creation to succeed.

  1. Following our API documentation, run the following command with the bearer token you just copied.
JWT=<Bearer token>
curl --request POST \
     --url https://api.gridx.de/account/tokens \
     --header 'Accept: application/vnd.gridx.v2+json' \
     --header 'Content-Type: application/json' \
     --header "Authorization: Bearer $JWT" \
     --data '{"description": "My org token", "expiresAt": "2030-01-01T00:00:00Z"}'

WARNING
By default, the token will have the same permissions as the authenticated user.
To specify a set of policy groups for the organizational token, you will need to have the AccountsUsersWrite permission and set the adequate group IDs in the groups attribute.

The response will include a token field with the token string, this is the only time you will be able to retrieve it!
Treat this token as any other form of credentials.

Using an organizational token

Just like a bearer token, an organizational token is used in the authorization header of the request. The only difference lies in the prefix Token instead of the usual Bearer:

GRIDX_TOKEN=<Org Token>
curl --request GET \
     --url https://api.gridx.de/systems \
     --header 'Accept: application/vnd.gridx.v2+json' \
     --header 'Content-Type: application/json' \
     --header "Authorization: Token $GRIDX_TOKEN"

Rotating an organizational token

For security reasons, it is strongly recommended to set an expiry date to your tokens and rotate them frequently.
This can be done through our rotation endpoint which additionally allows you to create a new token and specify its lifetime.

For instance, you can create a new token that will be valid one month longer than the original token specified in {tokenID} by one month with the following API call.
Please note that this does now change the existing token, but generates a new one with the extended lifetime.

curl --request POST \
     --url https://api.gridx.de/account/tokens/{tokenID}/rotate?lifetime=1M \
     --header 'Accept: application/vnd.gridx.v2+json' \
     --header 'Content-Type: application/json' \
     --header "Authorization: Token $GRIDX_TOKEN"

The overall flow thus looks like the following:

flowchart TD
    A[Log in as admin] -->|Copy Bearer Token| B(Create Org token)
    B -->|POST /account/tokens| C{Token about<br> to expire}
    C -->|yes| D[rotate token]
    C -->|no| E[make API call]
    D --> E
3 Likes