Authentication (External)

To execute authenticated calls against the API as an external consumer, (see thedocumentation for individual endpoints where it will indicate if that endpointrequires, or would benefit from, authentication), you need to include aJSON Web Token (JWT) in theAuthorization 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 akey andsecret from theAPI Credentials Management Page.

Note

Keep your API keys secret andnever commit them to a public code repositoryor 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 for each request

Prior to making every API request, you need to generate a freshJWT.The JWT will have a short expiration time and is only valid for a singlerequest so you can’t cache or reuse it.You only need to include a few standard fields; here’s what the raw JSON objectneeds to look like before it’s signed:

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

This is astandard JWT claim identifyingtheissuer. Set this to theAPI key you generated on thecredentials management page.For example:user:543210:23.

jti

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

iat

This is astandard JWT claim indicatingtheissued at time. It should be a Unix epoch timestamp andmust be in UTC time.

exp

This is astandard JWT claim indicatingtheexpiration time. It should be a Unix epoch timestamp in UTC timeand must beno longer than five minutes past the issued at time.

Changed in version 2016-10-06:We increased the expiration time from 60 seconds to five minutesto workaround support for large and slow uploads.

Note

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

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

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ5b3VyLWFwaS1rZXkiLCJpYXQiOjE0NDcyNzMwOTYsImp0aSI6IjAuNDczNjI5NDQ2MjM0NTU0MDUiLCJleHAiOjE0NDcyNzMxNTZ9.TQ4B8GEm7UWZPcHuNGgjzD8EU9oUBVbL70Le1IeuYx0

Note

Seejwt.io debugger for more information about the token.

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

Here is an example of creating a JWT inNodeJSusing thenode-jsonwebtokenlibrary:

varjwt=require('jsonwebtoken');varissuedAt=Math.floor(Date.now()/1000);varpayload={iss:'your-api-key',jti:Math.random().toString(),iat:issuedAt,exp:issuedAt+60,};varsecret='your-api-secret';// store this securely.vartoken=jwt.sign(payload,secret,{algorithm:'HS256',// HMAC-SHA256 signing algorithm});

Create an Authorization header

When making each request, put your generatedJSON Web Token (JWT)into an HTTP Authorization header prefixed withJWT, like this:

Authorization:JWTeyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ5b3VyLWFwaS1rZXkiLCJpYXQiOjE0NDcyNzMwOTYsImp0aSI6IjAuNDczNjI5NDQ2MjM0NTU0MDUiLCJleHAiOjE0NDcyNzMxNTZ9.TQ4B8GEm7UWZPcHuNGgjzD8EU9oUBVbL70Le1IeuYx0

Example request

Using theprofile 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.