JSON Web Token (JWT) Authentication

Integrations to LeadDesk can use a JSON Web Token (JWT) to pass info about a logged-in user from LeadDesk to another system. This avoids forcing the user to login separately to that other system.

A target system that receives a JWT must check the presence of the ver field in it and parse the rest of the JWT based on the version number.

In addition, the target system must verify that

• the signature in the JWT is correct (see Signature below),
• the token has not expired, i.e. the expiry timestamp (exp) is not in the past, and
• the audience (aud) matches the target system’s unique name/identifier.

Signature

Identity JWTs are not encrypted, but they are signed using LeadDesk’s private keys. This means that, before accepting a JWT as valid, its signature (i.e. the third and final part) must be verified using the corresponding public key.

The header (first part) of the decoded JWT contains the key ID ( kid ) of the private key that the JWT was signed with. The public counterpart can be retrieved using our REST API.

Example command to retrieve all the currently active keys:
curl -s -X GET “https://restapi-nor.leaddesk.com/stable/public_keys/signature/pem”

Expiry time

By default, an Identity JWT expires in 120 seconds.

Data structure

• ver – (integer) the version number of the structure
• aud – (string) the audience/system the token is for (contact us if you wish to add your solution)
• exp – (integer) the token’s expiry time as a Unix timestamp
• user
  • id – (integer) the user’s id
  • name – (string) the user’s full name
  • role – (string) the user’s role (agent, admin, teamleader, sponsor, manager)
  • email – (string) user’s email address
  • lang – (string) user’s language as a ISO 639-1 two-letter code
• client
  • id – (integer) LeadDesk client id
  • name – (string) the name of the client