Authentication (External) — addons-server documentation (original) (raw)

To execute authenticated calls against the API as an external consumer, (see the documentation for individual endpoints where it will indicate if that endpoint requires, or would benefit from, authentication), you need to include aJSON Web Token (JWT) in the Authorization header for every request. This header acts as a one-time token that authenticates your user account. No JWT claims are made about the actual API request you are making.

If you are building an app that lives on the AMO domain, read thedocumentation for internal authentication instead.

Access Credentials

To create JWTs, first obtain a key and secret from theAPI Credentials Management Page.

Note

Keep your API keys secret and never commit them to a public code repository or share them with anyone, including Mozilla contributors.

If someone obtains your secret they can make API requests on behalf of your user account.

Create a JWT

Prior to making API requests, you need to generate a JWT. The JWT will have a short expiration time but can be re-used until they expire. You only need to include a few standard fields; here’s what the raw JSON object needs to look like before it’s signed:

{ "iss": "your-api-key", "jti": "0.47362944623455405", "iat": 1447273096, "exp": 1447273156 }

iss

This is a standard JWT claim identifying the issuer. Set this to the API key you generated on thecredentials management page. For example: user:543210:23.

jti

This is a standard JWT claim declaring a JWT ID. This value needs to have a high probability of being unique across all recent requests made by your issuer ID. This value is a type ofcryptographic noncedesigned to preventreplay attacks.

iat

This is a standard JWT claim indicating the issued at time. It should be a Unix epoch timestamp andmust be in UTC time.

exp

This is a standard JWT claim indicating the expiration time. It should be a Unix epoch timestamp in UTC time and must be no longer than five minutes past the issued at time.

Note

If you’re having trouble authenticating, make sure your system clock is correct and consider synchronizing it with something liketlsdate.

Take this JSON object and sign it with the API secret you generated on thecredentials management page. You must sign the JWT using the HMAC-SHA256algorithm (which is typically the default). The final JWT will be a blob of base64 encoded text, something like:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ5b3VyLWFwaS1rZXkiLCJpYXQiOjE0NDcyNzMwOTYsImp0aSI6IjAuNDczNjI5NDQ2MjM0NTU0MDUiLCJleHAiOjE0NDcyNzMxNTZ9.TQ4B8GEm7UWZPcHuNGgjzD8EU9oUBVbL70Le1IeuYx0

Note

See jwt.io debugger for more information about the token.

Enter secret in the “VERIFY SIGNATURE” section to correctly verify the signature.

Here is an example of creating a JWT in NodeJSusing the node-jsonwebtokenlibrary:

var jwt = require('jsonwebtoken');

var issuedAt = Math.floor(Date.now() / 1000); var payload = { iss: 'your-api-key', jti: Math.random().toString(), iat: issuedAt, exp: issuedAt + 60, };

var secret = 'your-api-secret'; // store this securely. var token = jwt.sign(payload, secret, { algorithm: 'HS256', // HMAC-SHA256 signing algorithm });

Example request

Using the profile as an example endpoint, here’s what a JWT authenticated HTTP request would look like incurl:

curl "https://addons.mozilla.org/api/v5/accounts/profile/"
-H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ5b3VyLWFwaS1rZXkiLCJpYXQiOjE0NDcyNzMwOTYsImp0aSI6IjAuNDczNjI5NDQ2MjM0NTU0MDUiLCJleHAiOjE0NDcyNzMxNTZ9.TQ4B8GEm7UWZPcHuNGgjzD8EU9oUBVbL70Le1IeuYx0"

Find a JWT library

There are robust open source libraries for creating JWTs inall major programming languages.