When you create an API key (Settings → API keys → New API key) you choose exactly what the key may do. Each permission is called a scope. Give a key only the scopes its tool needs.
Quick tip: start read-only
Click Read-only to tick every "read" scope you are allowed to grant, then add write scopes one by one. Clear unticks everything.
What each scope allows
| Group | Scope | What it allows |
|---|---|---|
| Posts | POSTS_READ |
View posts, drafts and hashtag sets. |
| Posts | POSTS_WRITE |
Create, edit and delete posts. |
| Accounts | ACCOUNTS_READ |
List connected accounts, brands and what each channel supports. |
| Accounts | INSTAGRAM_ACCOUNTS_READ |
List connected Instagram accounts. |
| Media | MEDIA_READ |
Browse the media library and stock photos. |
| Media | MEDIA_WRITE |
Upload files to the media library. |
| Schedule | SCHEDULE_READ |
Read the best times to post and the next free slot. Owner only. |
| Analytics | ANALYTICS_READ |
Read account and post performance numbers. Owner only. |
| Webhooks | WEBHOOKS_WRITE |
Create, list and delete webhook subscriptions that send workspace events to a URL. Owner only. |
| Approval | POSTS_AUTO_APPROVE |
Let posts created with the key skip human approval when the request asks for it. The agent publishes without human review. Owner only. |
Why some scopes are greyed out
Scopes marked Owner only can be granted by a workspace owner only. If you are an admin they appear greyed out with the note "Only a workspace owner can grant this". Ask your workspace owner to create the key.
Approval: on by default, and who reviews
Every post an API key or an AI agent (MCP) creates waits for human approval by default. Nothing is published until someone approves it.
When creating a post, the create_post tool (and POST /public/posts) accepts an optional approval object:
{ "approval": { "mode": "required", "approverId": "<member id>", "message": "Please check the discount wording" } }
mode:"required"(default) or"none".approverId: send the post to one specific team member for review (they alone get the review notification and email). Use the newlist_approverstool to see who can approve (id and name only). A member outside your workspace, or without the right to approve, is rejected with a 400 and no post is created.approverEmail: an external reviewer (for example a client) who receives a review link by email, as in the Composer.message: a note shown to the reviewer.
Any key may choose a reviewer. Only a key with the owner-granted POSTS_AUTO_APPROVE scope may use "mode": "none" to publish without approval; any other key gets a 403 and nothing is created. A brand set to owner requires approval (and the client approval flow) still forces approval even with "none". An agent can never approve or reject posts itself.
Risk: prompt injection. An AI agent that reads untrusted content (web pages, emails, comments) can be tricked into acting on instructions hidden in it. With POSTS_AUTO_APPROVE such an agent can publish to your accounts with no human check. Grant the scope only to keys whose agent never handles untrusted input, and prefer the default (approval required) otherwise. Every post published this way records which API key created it.
Good to know
- The key is shown once, right after you create it. Copy it immediately.
- Revoke a key at any time from the API keys page; tools using it lose access immediately.
- A revoked or expired key stays in the list until you delete it (key menu → Delete). Deleting is permanent; an active key must be revoked first. Posts created with a deleted key keep working and show "scheduled via a deleted API key".
- Set an expiry date for keys used in temporary projects.