Authenticating With Partner Keys

This tutorial will walk you through using a partner key to generate an authentication token and make authenticated calls to the Help Lightning API.

Please make sure you have read through both the Partner Key Setup and the API Keys.

You will need:

• Partner Key Private Key
• Your Site ID
• API Key
• Python 3
• pyjwt (pip install pyjwt)

Help Lightning’s Partner Keys allow you to generate your own JWT tokens rather than requesting a token from Help Lightning. This token is then signed with your private key, which Help Lightning can validate with your public key.

This allows you to generate a new short-lived token for every authenticated request you make to the Help Lightning API.

A JWT token is just json data with special keys that is then signed with a private key. Help Lightning requires the following keys:

• iss :: Issuer
• sub :: Subject
• aud :: Audience
• exp :: Expiration

The iss must be Ghazal. The aud must also be Ghazal. The sub must be Partner:SITE_ID, where you replace with your SITE_ID. The exp is an expiration date of your choice. After this time, the token is no longer valid.

Pretend your Site ID is: 54344, then your JWT would look like:

{
  "iss": "Ghazal",
  "sub": "Partner:54344",
  "aud": "Ghazal",
  "exp": 1516239022
}

#!/usr/bin/env python3

# Configuration
partner_key = '/home/user/HelpLightingKey.pem' # Change to the path of your private key
timeout = 60 # 60 seconds
site_id = 54344 # Change to your site id

# import the libraries we need
import jwt
import datetime

# Open up our partner key
with open(partner_key) as f:
    # create an expiration date of 1 minute in the future
    exp = datetime.datetime.utcnow() + datetime.timedelta(seconds = timeout)
    
    # Create our basic JWT payload
    payload = {
        'iss': 'Ghazal',
        'sub': f'Partner:{site_id}',
        'aud': 'Ghazal',
        'exp': exp
    }

    # Read our private key into memory
    pkey = f.read()
    
    # Use the pyjwt library to sign our key using
    # the RS256 algorithm
    token = jwt.encode(payload = payload, key = pkey, algorithm = 'RS256')

    # Print the Token.
    # You can use this token directly in requests as
    #  part of the Authorization header
    print("Help Lightning token:\n")
    print('-'*50)
    print(token)
    print('-'*50)