Authentication

API key for integrations, dashboard session for the browser. How each mode works, the request limits and the error envelope shared by the whole API.

The API accepts two access modes, never both in the same request.

API key

This is the mode for integrations. Send the key in the x-access-key header on every call. The key identifies a project: everything you create or read belongs to it.

Header

x-access-key: pm_live_…

Rules:

The key is shown once, when created under API keys in the dashboard. The API stores only its hash.
Use the key on the server only. The API's CORS policy does not accept x-access-key from a browser.
Revoke and create another whenever you suspect a leak. Revocation is immediate and idempotent.
GET /v1/health/auth confirms the key is valid and returns the project.

Dashboard session

The dashboard talks to the same API with the user's session: Authorization: Bearer <token> plus the x-project-id header to say which project to act on. This mode exists for the browser and for the account routes (/v1/me, API keys), which accept Bearer only.

If you are integrating a system, use the API key. A request carrying both x-access-key and Authorization: Bearer is rejected with 401 UNAUTHORIZED.

Request limits

Limits count per credential (the key, or the token) per minute. A request rejected by authentication counts too, so a wrong key cannot be retried without bound.

Bucket	Limit	Routes
Default	300/min	Every resource route: accounts, posts, profiles
Upload	60/min	`POST /v1/media`
Account	60/min	`/v1/me`, organization, list and revoke keys
Create key	10/min	`POST /v1/projects/:id/api-keys`
Public	60/min per IP	OAuth callback, Meta callbacks, OpenAPI spec

Every response carries the x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset headers. Past the limit the API answers 429 with code RATE_LIMIT_KEY; wait for the reset before retrying.

Beyond that, each Instagram account has Meta's own publishing quota (100 posts per 24 hours). Postmatic checks the quota before accepting a post; when exhausted, the response is 409 RATE_LIMIT_ACCOUNT.

Error envelope

Every error comes in the same shape, with a stable code for your code to branch on and a message for humans.

Error example

{
  "statusCode": 409,
  "code": "TOKEN_INVALID",
  "message": "a conta precisa ser reconectada",
  "details": { "accountId": "int_…" }
}

Always decide on code, never on the message text, which is written in Portuguese and may change. The full list is in Errors.

Environments

Each project has an environment, currently always live. The key carries the environment in its prefix (pm_live_). There is no sandbox: test with a professional test account and publish for real.