Authentication and keys

How to create a key, use it in requests and keep it safe.

PlaygroundSee the reference
On this page
  1. Documentation
    2.  » 
  2. Authentication and keys
Updated on 3 min read
View as Markdown

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

PrefixTypeWhat it does
sandbox_SandboxReads actual account data. Writes are simulated and never charge.
prod_ProductionReads 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 Meu Interweb. 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:

  1. Your current password. If you sign in with Google or Facebook and have no usable password, you only need the code.
  2. 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

SituationResponseCode
The key is missing or not valid401unauthorized
The key was revoked or has expired401unauthorized
The person who created the key no longer has access to the account401unauthorized
The account cannot use the API at the moment403forbidden
The source IP is not on the key's list403ip_not_allowed
The key does not have the required permission403insufficient_scope
The API is switched off503disabled

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.