Payload

The payload portion of the JWT identifies the API account the request is for. It also includes timestamp information to limit the validity, and a nonce (as a "jti" value) to prevent replay attacks.

Field Name Type Example Comments
iss Issuer string "appnotch.com" Must be set to "appnotch.com"
sub Subject string "example" Identifies your API account (similar to a user name)
iat Issued At integer 1457036612 UNIX timestamp of when the token was created, required if exp is not present
exp Expires integer 1457037612 UNIX timestamp of when the token will be considered expired, required if iat is not present
jti JWT Token Id string "NONCE" A unique token string, effectively a nonce, must be unique to each request, cannot be the empty string

UNIX timestamps are defined to be the number of seconds since midnight Jan 1, 1970 UTC. A JWT processed by the API MUST contain either the iat (Issued At) and/or exp (Expires) timestamps.

Every request must have a unique payload. The jti value cannot be re-used*, even if the requested operation failed (400-599 HTTP status codes) or was incorrectly sent over HTTP instead of HTTPS. For each request, it is recommended to generate a GUID or a sufficiently random string to ensure no two requests have the same jti value within a 30 minute span.

A JWT is considered valid, if when received:

  • iat (if specified) is 3 minutes before or after (to account for clock skew) the current UTC time
  • exp (if specified) is less than 30 minutes in the future and the current UTC time is before exp
  • If both iat and exp are specified, both must pass and the time must be before whichever expires first
  • jti has not been used before* for by sub
  • The signature portion (HMAC) of the JWT is valid according to the RFC specification using the secret API key for sub

* Technically a jti value can be reused after the original token would have expired, and thus the iat or exp would have to be different to be considered a valid token.