# PostZen — sign up and get an API key

You are a coding agent setting up PostZen for your user. Follow these steps in
order to get them a PostZen account and an API key, then store the key in their
project. PostZen is a REST API for publishing and scheduling social media posts
across 9 platforms. Base URL: `https://api.postzen.dev` (API paths are prefixed
with `/v1`).

After this, follow `https://www.postzen.dev/agent-quickstart.md` to wire the
key into the codebase.

## Step 0 — Skip if already configured

If `POSTZEN_API_KEY` is already set in the environment or present in a `.env`
file at the project root, the user is already authenticated. Stop here and move
on to integration (`https://www.postzen.dev/agent-quickstart.md`). Do not
create a second key.

## Step 1 — Start a device authorization

```bash
curl -sS -X POST https://api.postzen.dev/auth/cli/initiate \
  -H 'Content-Type: application/json' \
  -d '{"deviceName":"Agent Setup"}'
```

Response:

```json
{
  "deviceCode": "pzn_dc_...",
  "userCode": "PZ-7KMQ2X",
  "browserUrl": "https://app.postzen.dev/connect/cli?code=PZ-7KMQ2X",
  "expiresAt": "2026-01-01T00:15:00.000Z",
  "interval": 5
}
```

Keep `deviceCode` secret (it is the polling credential). Note `browserUrl` and
`interval`. The session expires at `expiresAt` (15 minutes).

HTTP `429` `{"error":"rate_limited"}` means too many setup attempts from this
machine — wait a minute or two and retry Step 1.

## Step 2 — Ask the user to authorize

Show the user the `browserUrl` and ask them to open it in their browser. There
they sign up (or log in if they already have an account) and click
**Authorize**. This is the only manual step.

> Open this link to connect PostZen: `<browserUrl>`
> Sign up or log in, then click Authorize. I'll wait.

## Step 3 — Poll until authorized

Poll the `poll` endpoint with **HTTP GET** (not POST — POST returns `405`),
every `interval` seconds (5s minimum — faster polling returns `429`
`{"status":"slow_down"}`), using the `deviceCode` as a Bearer token:

```bash
curl -sS -X GET https://api.postzen.dev/auth/cli/poll \
  -H "Authorization: Bearer <deviceCode>"
```

Responses:

- `{"status":"pending"}` — keep waiting, poll again after `interval` seconds.
- `{"status":"authorized","apiKey":"pzn_live_..."}` — success. **The `apiKey`
  is returned exactly once, on this first authorized poll.** Every later poll
  returns `{"status":"authorized"}` with NO `apiKey`. Do Step 4 immediately
  with this response, before doing anything else (do not re-poll, do not mask
  or discard the value first).
- `{"status":"denied"}` — the user declined. Stop and tell them.
- HTTP `410` — the session expired. Restart from Step 1.
- HTTP `429` `{"status":"slow_down"}` — you polled too fast. Wait `interval`
  seconds and poll again.

## Step 4 — Store the key (do this the instant you get it)

The moment the authorized poll returns the `apiKey`, write it to the project's
`.env` file before anything else:

```
POSTZEN_API_KEY=pzn_live_...
```

Make sure `.env` is in `.gitignore`. After it is persisted, **never print the
key to the terminal or commit it.** Confirm success to the user without echoing
the secret value. If you lose the key before persisting it (e.g. you polled
again first), it is gone — PostZen stores only a hash. Restart from Step 1 to
mint a new one.

The key has Read & Write permission across all profiles and is named after
`deviceName` (e.g. `Agent Setup`) on the PostZen dashboard's API Keys page
(`https://app.postzen.dev/api-keys`), where the user can revoke it at any time.

## Next

Integrate PostZen into the codebase:
`https://www.postzen.dev/agent-quickstart.md`.