JWT token

HipChat to add-on HTTP calls

Any request made by HipChat to your add-on configuration page will include a JSON Web Token (JWT), an encoded form of JSON data and a signature to verify its contents. It is recommended you use one of the existing JWT libraries to decode the token. You can use the JWT token to validate that:

The request comes from HipChat

The request comes from the right installation

The request was not altered in transit

The JWT token is included either:

in the HTTP header "Authorization"

in the request parameter: "signed_request"

JWT tokens are base64 encoded. Once decoded, the JWT token is made of 3 elements delimited by a "."

Header

Payload

Signature

The payload contains the following elements, which provide contextual information about the call:

Attribute

Description

iss

Issuer: OAuth Client ID

sub

Subject: User ID

iat

Issued at timestamp

exp

Expiration timestamp

jti

JWT ID (random 20 chars)

context

Custom attributes:

user_tz

User timezone

room_id

Room ID

The token is signed. You can verify its signature using the sharedSecret sent during installation.

Here are the steps to handle a JWT token:

Extract the token from the request. Depending on the call:

from the HTTP header "Authorization"

from the request parameter: "signed_request"

Decode the base64-encoded token

Extract the oauthId which is in the 'iss' (issuer) parameter from the JWT token