Authentication and keys

How to authenticate

Send the key in the Authorization header, on every request:

Authorization: Bearer sandbox_...

The API only accepts the key in this header, never in the URL. The request must use HTTPS.

The GET /v1/ping and GET /v1/openapi.json operations do not need a key.

Key types

Prefix	Type	What it does
`sandbox_`	Sandbox	Reads actual account data. Writes are simulated and never charge.
`prod_`	Production	Reads and changes your account.

The prefix is followed by 43 random characters. The address is the same in both modes: the key decides. See Sandbox and Production.

Create a key

Keys are created on the API page, inside My MozOut. A key can never create another key.

The owner of an account with an active service or domain can create keys. Each account can have up to 20 keys.

When you create one, you choose:

Name: so you can recognise the key later.
Mode: Sandbox or Production.
Permissions: what the key can do. See Permissions.
Validity: 30, 90 or 365 days, or no expiry. The default is 90 days.
IP list: optional. If you fill it in, the key only works from those addresses.
Spending limit: the maximum amount over 30 days. See Spending limit.

To confirm, the page asks for:

Your current password. If you sign in with Google or Facebook and have no usable password, you only need the code.
A 6-digit code sent by email, valid for 10 minutes, with 5 attempts.

Once the key is created, you receive a notice by email.

The key is shown only once

The key appears a single time, when it is created. We keep only a cryptographic hash and the last 4 characters, so we cannot recover it. If you lose it, revoke it and create another.

When a key stops working

Situation	Response	Code
The key is missing or not valid	401	`unauthorized`
The key was revoked or has expired	401	`unauthorized`
The person who created the key no longer has access to the account	401	`unauthorized`
The account cannot use the API at the moment	403	`forbidden`
The source IP is not on the key's list	403	`ip_not_allowed`
The key does not have the required permission	403	`insufficient_scope`
The API is switched off	503	`disabled`

What a key can never do

Whatever its permissions, a key can never:

create another key;
change the account password or email;
see card details.

Keep your key safe

Keep it in an environment variable or a secrets vault, never in code or in a repository.
Use the key only on your server. Browsers can only call the API from this documentation, so your website's pages cannot use the key directly.
Create one key per program, with the minimum permissions and a short validity.
If an IP list is possible in your case, use it.
If the key is exposed, revoke it straight away on the API page.

See the key in use

The GET /v1/token operation shows the permissions, validity and limits of the key that made the request. The key itself is never returned.