Tokens

Every API that requires authorization uses a token. This token should be passed in as part of the Authorization HTTP header.

In Help Lightning, a Token is represented in the standard JWT format and can be decoded using standard JWT tools. Each token encodes the following information:

iat - Issued at Date :: When the token was created
exp - Expiration Date :: When the token expires
iss - Issuer :: This will always be Ghazal
sub - Subject :: The type of object this token represents. See the Subject section below
pem - Permissions :: The permissions set

The token is then signed with a private key by Help Lightning so that the system can verify it has not been tampered with and is authentic.

Subjects

The Help Lightning API allows interaction with many different types of Help Lightning objects, including Users, Enterprises, Groups, and Sessions/Calls.

Various APIs expect an authorization token with a subject that represents the correct object. Typically, a user starts by authenticating and is returned a token that represents their user with a specific set of permissions. The user can then using “transition APIs” to “exchange” one type of token for another. For example, if a user has a user token, and wants to make changes to the enterprise (assuming they have permission), then they can use the /enterprises API to get a token that represents their enterprise. The new enterprise token can then be used to make modifications on that specific enterprise.

This exchange of tokens can cascade and can allow a user to act on behalf of another user. For example a site administrator can exchange their user token for an enterprise token. They can then get a specific employee in their enterprise and exchange for a token representing that employee. The site admin can then use this employee token to act on behalf of that employee and make modifications to that employee.

Permissions automatically cascade through the exchange of tokens, determining what operations are allowed to be performed.

The subjects that are used in the API are:

User :: Can be used with all user APIs
Refresh :: Special token to get a new user token without having to reauthenticate
Enterprise :: Can be used with all enterprise APIs
Session :: Can be used to interact with sessions/calls
Partner Tokens :: These are a special token. See Partner Keys for more information.

Request Headers

The primary token is always passed in as part of the HTTP Authorization Header. For example:

curl \
  -H 'Authorization: eyJhbGc...557g' \
  -H 'Content-type: application/json' \
  https://api.helplightning.net/api/v1/info

Some APIs will take additional tokens as part of the request body, however the primary token will still be in the Authorization header.