Partner Keys

Help Lightning has several methods for handling authentication without our API. For server side integrations, Help Lightning recommends the use of our Partner Keys.

A Partner Key allows the integrator to interact with the API at the enterprise level. It also can allow acting on behalf of users in your enterprise. For example, you could act on behalf of one of your users to start a call and open up an authenticated browser window, entering the user directly into the call.

A Help Lightning Partner Key consists of two parts: the public key and the private key. The public key is shared with Help Lightning, but the private key must never be shared and must be protected. It should never be embedded into a front end application!

When using a partner key, the integrator will generate a JWT token, then use their private key to sign the token. Help Lightning will use the public key to verify the signature. At that point, the integrator is considered authenticated and has access to all the enterprise level APIs.

The use of a Partner Key requires a backend server that is in control of the integrator. Web Clients send requests to the integration backend through whatever authentication system you would normally use, then the integration server uses the Partner Key to interact with the Help Lightning API on behalf of the user. The web client never interacts with the Help Lightning API directly.

Here is an example of how this works:

A Partner Key can be generated by Logging into https://helplightning.net, going to Admin -> Workspace Settings and choosing the Developer Tab.

If you create a new Partner Key, you will be prompted to download the Private part of the key pair. Help Lightning will store the public key and will make it visible, so you can confirm your keys.

Help Lightning will never store your private key! If you are concerned about having the private key be available in transit, you can also create your own key pair using openssl and paste your public key into the Help Lightning field.

A workspace can only have one Partner Key at a time. Generating or uploading a new key immediately disables the previous key!

While Help Lightning NEVER stores the private key, it is valid to have concerns about having the valid key be generated by Help Lightning and transmitted across the wire. That is also why Help Lightning allows for creating the public/private key pairs offline and uploading only the public key to Help Lightning.

You can use a variety of tools for this, but the following example shows how to do this with the openssl command.

First a private key is generated and saved as private.pem

openssl genrsa -out private.pem 1024

Then a public key is created from the private key. The public key must use the RSA PublicKey Format and be PEM encoded.

openssl rsa -in private.pem -outform PEM -RSAPublicKey_out -out public.pem

You can then log into helplightning.net, go to Admin -> Workspace Settings and choose the Developer Tab. Under Partner Key, choose Edit and copy the contents of the public.pem file into the text entry and save it.

All Help Lightning API endpoints require an Authorization token to be passed in as part of the Authorization header. Tokens are in the JWT format and must be signed. Tokens can represent a User, an Enterprise, a Session, and other objects in the Help Lightning system, depending on which API endpoints you are using.

Typically, JWT tokens are generated and signed by the Help Lightning server upon authentication. However, Partner Keys allow enterprises to create their own JWT tokens and sign them with their private Partner Key. The Help Lightning system will validate the JWT token and verify the signature using the paired public key.

A JWT token is just a simple JSON data structure, and there are libraries for almost any programming language to help create and sign them.

When creating a JWT and signing it with a Partner Key, Help Lightning expects the following attributes in the JWT token:

{
  "iss": "Ghazal",
  "sub": "Partner:$SITE_ID",
  "aud": "Ghazal",
  "exp": $EXPIRATION_DATE
}

The JWT token must also be signed with your private partner key using the RS256 algorithm.

Make sure you replace $SITE_ID with your site’s workspace id. Also, Help Lightning recommends that you generate a token with a short expiration date (1-15 minutes) since a leaked token with a long expiration can become a security risk.