API Authentication

HTTPS Required

All requests and responses to the API MUST be done over HTTPS. Requests done through normal HTTP will result in a 403 Forbidden response given.

JSON Web Tokens (JWT)

The API authentication scheme uses JSON Web Tokens in the HTTP Authorization header of requests made to it. See jwt.io for more information and client libraries for using and working with JWTs.

Every request will need to have the Authorization header set with the Bearer scheme. The following is an example of the header with a JWT.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhcHBub3RjaC5jb20ifQ.7ZShzsQMi25Vh40QeMcNNUpouXe5rrkgluYjDyma6RI

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.

Example Payload

The following example payload is for a token with the subject/account named "MY ACCOUNT" and generated (issued at) Mar 3, 2016 21:32:56 UTC.

{
   "iss": "appnotch.com",
   "sub": "MY ACCOUNT",
   "iat": 1457040776,
   "jti": "NONCE VALUE"
}

Header and Signature

The signature for the JWT is computed using your API account's secret key. Currently only the HS256 (HMAC SHA256) signature scheme is supported. This means that the header portion of the JWT will always have alg set to HS256, and the typ set to JWT. Additional values may be present in the header or payload, but are ignored (except for verifying the signature of course).