fbpx

Authentication

Periodic uses a secure and convenient authentication system that allows shared access on a limited basis, known as JWT.

Visit jwt.io to generate JWT.

What is JWT?

JWT stands for “JSON Web Token,” and is an open standard for delegating authority to make one-off API calls.  More details can be found on the official JWT standard website, but the basic concept is of issuing limited-use web tokens that authorise single transactions against an API.  

Getting started with JWT

The token consists of three separate parts: a header, a payload, and a signature.  The header specifies what version of JWT is being used, the payload is the information transmitted, and the signature is a digest (in Periodic’s case, a SHA256 HMAC digest) of the concatenated, base64-encoded header and payload.

The token itself is each of these three sections joined by periods (‘.’) and prefixed with “Bearer “.  The complete message is sent as the value of the WWW-Authenticate header.

Header

The header field is simply the following JSON object base64-encoded:

{ “alg”: "HS256", “typ”: "JWT" }

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

// This will always be your header section.

Payload

The payload section is a base64-encoded JSON object representing various claims.  “Claims” is a term of art in JWT meaning, basically, key-value pairs, some of which are standardized.  Periodic currently only supports the iss, iat, sub, nbf, exp, and jti claims.  Of these, iss, iat, and sub are required.

iat (“issued at”): a number representing the UNIX timestamp at which the token was issued
iss (“issuer”): the username of the user making the request.  Periodic uses this to identify the user
sub (“subject”): the whitelabel name (providersubdomain.whitelabelname is also acceptable) on which the request is being made.  Unless you have set up your own marketplace, this is just “periodic”
exp  (“expires at”): a UNIX timestamp indicating when this token expires.  If neither exp or nbf is included, the token expires one minute after the time given in iat
nbf  (“not before”): a UNIX timestamp indicating when this token becomes valid.
jti (“jwt identifier”): a unique ID for the token.  Clients may include this to track use of their tokens or to increase security

Signature

The signature is the base64-encoded SHA256 HMAC digest of the (base64-encoded) header and the (base64-encoded) payload concatenated with a period, hashed against the requesting user’s Periodic API key.

Example Token

The best way to get a feel for creating JWT tokens is to use the jwt debugger at the JWT standard website.  For convenience, we also provide the following example.

Imagine a user with api key “secret” and username “username” is making a request at 3:45pm on Friday, 16 June 2017.  The UNIX timestamp for this moment in time is 1497642359.

The payload will therefore be:

{ “iss”: “username”, “iat”: 1497642359, “sub”: “periodic” }

eyJpc3MiOiJ1c2VybmFtZSIsInN1YiI6InBlcmlvZGljIiwiaWF0IjoxNDk3NjI4MjA5fQ

View the full specification for the Reservation element.

That’s it! You can easily add more functionality once your booking app is up and running.