# Authentication and keys

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

Updated on 4 November 2026

## How to authenticate

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

```text
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`](https://docs.interweb.ao/en/key-status.md) and [`GET /v1/openapi.json`](https://docs.interweb.ao/en/key-status.md) 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](https://docs.interweb.ao/en/api-rules.md).

## Create a key

Keys are created on the [API](https://www.meu.interweb.ao/api-center.php?language=english&currency=2) 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](https://docs.interweb.ao/en/permissions.md).
- **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](https://docs.interweb.ao/en/permissions.md).

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

| 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](https://www.meu.interweb.ao/api-center.php?language=english&currency=2) page.

## See the key in use

The [`GET /v1/token`](https://docs.interweb.ao/en/key-status.md) operation shows the permissions, validity and limits of the key that made the request. The key itself is never returned.