> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.usglobalmail.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.usglobalmail.com/_mcp/server.

# Authentication

The API authenticates requests with an API key. Send it in the `Authorization` header as a bearer
token on every request:

```bash
curl https://api.usglobalmail.com/v1/mails \
  -H "Authorization: Bearer usgmk_live_…"
```

A missing or invalid key returns `401 Unauthorized` as `application/problem+json`.

## Key types

| Prefix         | Environment | Base URL                               |
| -------------- | ----------- | -------------------------------------- |
| `usgmk_live_…` | Production  | `https://api.usglobalmail.com`         |
| `usgmk_test_…` | Sandbox     | `https://api-sandbox.usglobalmail.com` |

A live key only works against production; a test key only works against the sandbox. Sending a test
key to production (or vice-versa) is rejected as `401`.

## Managing keys

Create, view, and rotate keys in your [USGM dashboard](https://inbox.usglobalmail.com/app/settings/developer/api-keys). Each key acts on
one customer's mailbox — everything the key can do runs as that customer.

> **Warning**
>
> Store keys in environment variables or a secrets manager, never in source control or client-side
> code. If a key leaks, rotate it immediately — a rotated key stops working right away.

## Best practices

* **One key per integration.** Use a dedicated key per app or agent so you can rotate one without
  disrupting the others.
* **Prefer the sandbox while building.** Point at `https://api-sandbox.usglobalmail.com` with a
  `usgmk_test_…` key until you're ready to handle live mail.
* **Rotate on a schedule** and on any suspected exposure.