> ## Documentation Index
> Fetch the complete documentation index at: https://postmesh.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

> Create, scope and revoke PostMesh API keys for the MCP server. Keys are shown once, stored hashed, and can only do what their scopes allow.

Keys let your assistant act for your account.

> [!NOTE]
>
> **In short:** Create a key in Settings, API & MCP. It starts with pm\_live\_, is shown once and is stored hashed, so copy it straight away. New keys can read and write drafts; posting is a switch you turn on. Send it as Authorization: Bearer \<key>. Revoke it there any time.

## Create and revoke

**1. Open Settings, API & MCP**

Name the key after where you'll use it, for example Claude Code. Switch on **Let it post and schedule** only if the assistant should publish.

**2. Copy it now**

The full key is shown once. PostMesh only keeps a hash.

**3. Revoke when done**

Revoking stops the key at once. A key made in Settings lasts until you revoke it. You can have up to 10 keys, and create up to 5 an hour.

## Scopes

Each key has scopes that say what it may do. New keys get `read` and `drafts`; **Let it post and schedule** adds `publish`.

| Scope | Lets the key |
| - | - |
| `read` | Read your accounts, posts, drafts, usage and analytics. Every key has it. |
| `drafts` | Save drafts and brand voice, and use the AI Agent |
| `publish` | Post, schedule, cancel and retry posts |
| `media` | Upload media and use Clip Factory |
| `accounts` | Connect or change social accounts |

A request its scopes don't cover gets status 403 with `"code": "api_key_scope"` and the `scope` it needs, and an MCP client sees only the tools its key may call. No key can manage keys, billing or your account. Keys made before scopes existed keep full access.

Signed in, `POST /api/post/api-keys` takes `scopes` (a list of the five above) and `expires_in_days` (1 to 365). Without `expires_in_days`, the key lasts until you revoke it.

## Ask before posting

A key that can post can wait for you instead. Switch on **Ask me before it posts** when you create the key, or **Ask first** on its row in Settings, API & MCP. From its next post on, whatever the key publishes or schedules is saved and marked Needs your approval, and nothing goes out until you approve it.

* Open the post in Posts. **Approve** sends it at its time, or within a minute if that time has passed. **Don’t post** stops it, and nothing is sent.
* Only you can approve, signed in to PostMesh. No API key can approve a post, its own or any other.
* While a key asks first, it can still cancel a scheduled post, but it can't retry, edit or send a post early.
* A few older keys can't ask first and don't have the switch. Create a new key instead.

> [!NOTE]
>
> YouTube can't wait for approval, so a key that asks first can't post there. Post to YouTube from PostMesh.

## Use a key

```http Header theme={null}
Authorization: Bearer pm_live_…
```

> [!WARNING]
>
> A key acts for your account within its scopes, and requests made with it run right away. Never paste it into a chat, a public repo or a support email. Clients that can't send headers can put the key in the MCP address (?api\_key=), but an address can end up in logs and history, so use the header when you can.

## REST API

Keys also work with the REST API at `https://postmesh.app/api/v1`. Send the key as `Authorization: Bearer pm_live_…`; each request needs the [scope](https://postmesh.app/docs/api-keys.md#scopes) that covers it.

```bash curl theme={null}
curl https://postmesh.app/api/v1/me \
  -H "Authorization: Bearer pm_live_…"
```

* Send an `Idempotency-Key` header, such as a UUID, with every POST. The same key within 24 hours answers with the first request's result instead of posting twice.
* Each key may make 120 requests a minute. Every answer carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`; over the limit, the answer is status 429 with a Retry-After header.
* The **API reference** group of these docs lists every endpoint with its fields and answers. It is generated from the [OpenAPI document](https://postmesh.app/api/v1/openapi.json).

## Rate limits

| Action | Limit |
| - | - |
| Publish or schedule | 10 a minute |
| Retry a failed post | 5 a minute |
| Save drafts | 30 a minute |
| MCP requests with a key | 120 a minute per key |
| MCP requests without a key | 60 a minute per address |
| REST API requests | 120 a minute per key |
| Create a key | 5 an hour, 10 keys at most |

Over the limit, requests get status 429 with a Retry-After header. The MCP server's own limits also answer with JSON-RPC error `-32029`, with `data.retryAfter` in seconds.


## Related topics

- [Who you are](https://postmesh.app/docs/api-reference/accounts/who-you-are.md)
- [Post to social media from Claude, Cursor and Codex (MCP)](https://postmesh.app/docs/mcp-setup.md)
- [Create a post](https://postmesh.app/docs/api-reference/posts/create-a-post.md)
- [Get analytics](https://postmesh.app/docs/api-reference/analytics/get-analytics.md)
- [Delete a draft](https://postmesh.app/docs/api-reference/drafts/delete-a-draft.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.