Fetching contributors…
Cannot retrieve contributors at this time
67 lines (54 sloc) 2.8 KB



Authorization is done by generating a JWT token for each request and putting it in the HTTP Authorization header with the auth-scheme JWT, under the auth-param token. Example (line breaks are for display purposes only):

Authorization: JWT token="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJrZXkiO\



Use the HS256 (HMAC-SHA256) algorithm. Example header:



  • key: Use "master" for now. TODO: update this when we implement specific consumer keys
  • exp: (Optional) Unix time for when this token should expire. A short value should be used, e.g. 30-60 seconds from the time of token generation. This is optional because of potential clock synchronization problems that can occur between servers, but it's highly recommended.
  • method: HTTP Method being used in this request. Should be GET, POST, PUT, or DELETE.
  • path: Relative HTTP path being requested, e.g. /systems/chicago or /systems/chicago/badges?archived=true. Note that any query variables should be represented in the path.
  • body: (Required on POST, PUT) An object with two fields:
    • hash: A hash of the entire contents of the body of the POST request, e.g. sha256('{"slug":"hi","name":"Hello"}')
    • alg: Just use sha256.


Ask one of us for the secret.

Example in JavaScript

var jws = require('jws')
var crypto = require('crypto')
var body = '{"slug": "some-system", "name": "Some System", "url":""}'
var computedHash = crypto.createHash('SHA256').update(body).digest('hex')
var token = jws.sign({
  secret: "supersecret",
  header: {typ: "JWT", alg:"HS256"},
  payload: {
    key: "master",
    exp: 1393436029,
    method: "POST",
    path: "/systems",
    body: {
      alg: "sha256",
      hash: computedHash

Purpose of Each Claim

  • key: To look up the secret used to sign the token.
  • exp: General protection against replay attacks: a short lived token has limited opportunity for re-use.
  • method: Protection from replay attacks against the same URL with a different method, e.g., converting a POST request into a DELETE request.
  • path: Protection from replay attacks with the same method but against a new URL, e.g, using the same token for a POST to /systems/chicago as the token for a POST to /systems/new-york.
  • body: Protection from data tampering; ensures the data that the client intended to send is the data received.