Getting started
Authentication
OAuth for AI assistants, keys for scripts, scopes and approvals.
Every request carries a bearer token. There are two kinds, and both work on MCP and the REST API.
| OAuth (Sign in with ZieAds) | Key | |
|---|---|---|
| Best for | Claude, ChatGPT, Cursor, Claude Code, VS Code | REST API, Zapier, Make, n8n, scripts, MCP clients that take headers |
| How you get it | The app opens a ZieAds screen and you choose Allow access | Create one in Settings, API and MCP |
| Lifetime | Access token 1 hour, refreshed by the app for 90 days | Until you revoke it |
| Where to revoke | Connected apps, Disconnect | Keys, Revoke |
Sending a key
Authorization: Bearer zk_your_keyKeys start with zk_. ZieAds stores only a SHA-256 fingerprint, so a lost key cannot be recovered. Create a new one and revoke the old one. You can have 10 active keys.
Scopes
| Scope | Allows |
|---|---|
read | Briefing, analytics, ads summary, posts, comments, competitors, account health and pending actions. Always included. |
draft | Create draft posts, draft comment replies and ask to track competitors. Every draft waits for approval. |
Approvals and auto approve
A draft action creates an approval request in ZieAds. You see it on the AI Analyst page and in the approvals list. When you approve it, ZieAds does the work, for example schedules the post. A key can skip approval for these actions only:
| Action | What happens when skipped |
|---|---|
schedule_post | A drafted post is scheduled right away for its time. |
send_reply | A drafted reply is sent to the comment. |
add_competitor | The brand is added to Competitor Hunt. |
Leave auto approve off until you trust a workflow. Every call is recorded in the activity log either way.
Keep keys safe
- Never put a key in front end code or a public repository.
- Use one key per tool, so you can revoke one without breaking the others.
- Give read only keys to tools that only read.