JSON Web Tokens (JWTs)

JSON Web Tokens (JWTs) are an industry standard authentication mechanism. A great introduction to the technology is available here, and a broad set of supported JWT libraries for a variety of languages and platforms are available.

A JWT is composed of a header, a payload, and a signature. The payload contains information called claims which describe the subject to whom the token was issued.

Before you can make calls to the Smooch API, you’ll need to create a JWT that proves you are authorized to use the API.

Step 1 Generate a secret key

From the Smooch dashboard, select your app and then select the settings tab. A secret key is composed of a key id and a secret, which you will use in the next step.

secret key and id

Step 2 Use the library available for your platform to create the JWT

We’ve included code samples for a few popular programming languages below. You can find libraries for more platforms here.


Using the jsonwebtoken NPM module:

var jwt = require('jsonwebtoken');
var token = jwt.sign({ scope: 'app' }, SECRET, { header: { kid: KEY_ID } });


Using the ruby-jwt gem:

require 'jwt'

payload = {:scope => 'app'}
jwtHeader = {:kid => KEY_ID}

token = JWT.encode payload, SECRET, 'HS256', jwtHeader


Using the pyjwt module:

import jwt
token = jwt.encode({'scope': 'app'}, SECRET, algorithm='HS256', headers={'kid': KEY_ID})

Step 3 Start using the Smooch API

The next section in this guide explains how to use the JWT to authenticate to the Smooch API and start performing operations using the platform.