Token Format
MILK API authentication tokens are JSON Web Tokens (JWT), which are signed with a JSON Web Signature (JWS)
- JWT Specification - http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-08
- JWS Specification - http://tools.ietf.org/html/draft-ietf-jose-json-web-signature-11
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:
- Header - specifies the format and signing
- i.e. {"typ":"JWT","alg":"HS256"}
- This example specifies signing with the HMAC-SHA256 algorithm.
- 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"
- Signature - Signature of the encoded header, joining '.' and the encoded claims, using the algorithm specified in the header.