# NextMsg auth.md

How an AI agent gets and uses credentials for the NextMsg API (`https://api.nextmsg.app`).

## Audience

AI agents, scripts, CI jobs and servers that **send** notifications to a person. Agents only send; they cannot read an inbox.

## How credentials are provisioned

There is no agent sign-up, OAuth flow or API registration. The **person** provisions the credential:

1. The person installs the NextMsg app (iOS or Android). The app creates their inbox and shows a **send key** (`snd_live_` followed by 48 hex characters) in Settings.
2. The person gives the key to the agent, usually as the environment variable `NEXTMSG_KEY`, or in the `env` block of an MCP client configuration.

If you are an agent without a key, ask the person for it. Do not try to create inboxes or keys yourself; inbox creation is reserved for the apps.

## Using the credential

Send it as a bearer token:

```http
POST https://api.nextmsg.app/v1/send
Authorization: Bearer snd_live_...
Content-Type: application/json

{"message": "Build passed on main", "channel": "ci"}
```

Or in the path of the quick URL (handy for tools that can only fetch URLs; the key then appears in logs and history, so prefer the header):

```http
POST https://api.nextmsg.app/p/snd_live_...
Content-Type: text/plain

Build passed on main
```

With the MCP server (`npx -y @nextmsg/mcp`), the key is read only from `NEXTMSG_KEY` and never passes through the model's context.

## Scope and limits

- A send key can only send to its own inbox. It cannot read messages, list devices or change settings.
- Messages: 1-640 characters; channel: 1-32 characters `[a-z0-9_-]`, default `general`.
- Free inboxes: 100 messages per month (then `402`). Bursts: 100 requests per 10 seconds (then `429`). Do not retry in a loop.

## Errors

| Status | Meaning |
|---|---|
| 401 | Missing, malformed, revoked or rotated key: ask the person for the current key |
| 402 | Free monthly limit reached |
| 413 | Message too long |
| 429 | Rate limited: wait before retrying |

## Rotation and revocation

The person rotates the key in the app (Settings). The old key stops working immediately and requests with it get `401`.

## More

- API specification: https://api.nextmsg.app/openapi.json
- Full guide: https://nextmsg.app/llms-full.txt