Token Format

MILK API authentication tokens are JSON Web Tokens (JWT), which are signed with a JSON Web Signature (JWS)

Basics

A signed JWT is a URL-safe string. The basic format consists of 3 parts, separated by dots as below:

{Base64 encoded JWT Header}.{Base64 encoded JWT Claims}.{Base64 encoded JWT Signature}

These 3 components are as follows:

  1. Header - specifies the format and signing
    •  i.e. {"typ":"JWT","alg":"HS256"}
    • This example specifies signing with the HMAC-SHA256 algorithm.
  2. Claims - specifies who issued the token, who should accept it, and the subject of the claims
    • i.e. {"iss":"application.example.com","aud":"api.milkbooks.com","exp":1373295769,"sub":"1234567890","email":"joe@bloggs.com"}
    • This example shows a token with the following claims
      • Issued by the servers at application.example.com
      • Intended for the live MILK API
      • That expires at a given time (UNIX timestamp in UTC)
      • For a user identified by the id "1234567890" in the external system
      • That has the email "joe@bloggs.com"
  3. Signature - Signature of the encoded header, joining '.' and the encoded claims, using the algorithm specified in the header.