OAuth apps for your own system: consent, tokens and the REST API
An OAuth app lets your own system act in an Agent Planners workspace: you register it on API & MCP → Your own OAuth apps, a person approves it once on the consent page, and your server calls the REST API with that connection's tokens. An app registered in a workspace and connected to it is that workspace's own app — its writes apply at once, with no approval step — while an app published to other workspaces waits for their approval by default. Connecting an AI agent such as Claude or Codex is a different path: see Connect Agent Planners to Claude, Codex, Grok and Muse.
Two tracks: an AI agent, or your own system
Agent Planners is reached two ways, and this page is the second. Both reach the same permissions, tools, guardrails, credits and audit trail; what differs is who holds the connection and who approves its changes.
- Track 1 — an AI agent (Claude, ChatGPT, Codex, Cursor, VS Code, Gemini CLI, Grok …): you add the MCP server https://www.agentplanners.com/api/mcp to the agent and sign in from the agent. MCP hosts sign in through OAuth behind the scenes — they register themselves, so there is nothing to set up here. The steps for each agent are in Connect Agent Planners to Claude, Codex, Grok and Muse. An agent's changes wait for approval by default and its raw writes are queued.
- Track 2 — your own system (this page): your software registers an OAuth app on API & MCP → Your own OAuth apps, a person approves it once on the consent page, and your server calls the REST API with that connection's tokens. A private app (Who can connect it: Only this workspace) is the workspace's own app: no approval step. A script or a CI job in your own workspace can use an API key instead.
- Track 2, published — a product that serves many Agent Planners customers, for example a UTM / link-management app that keeps the tracking templates in each customer's ad accounts up to date: register a published OAuth app (Who can connect it: Any workspace on Agent Planners). Each customer's admin connects it from their own workspace on the consent page and chooses its permissions and platforms; your server then calls the REST API with that customer's access token. Changes wait for a person in the customer's workspace unless that customer's admin chose to apply ordinary changes at once.
Your own app: no approval step
An OAuth app registered in a workspace and connected to that same workspace is the workspace's own app — your own system connected to itself. Its connections have no approval step: every write it sends applies at once — typed tools, raw requests (<family>__raw_request) and irreversible changes such as deletes included — and the consent page shows no Changes on your platforms choice for it, only a sentence that its changes apply at once.
- What still applies: the scopes and the platforms the person approved, the workspace boundary (a connection reaches exactly one workspace), the guardrails — budget caps, protected names, the spend cap — and the structural refusals that are not approvals (no money movement on Stripe, no Tag Manager publish over the API, writes no lane applies).
- A task your app starts (POST /api/v1/tasks) runs on the task lanes, whose person decisions are unchanged: autoApprove is accepted for your own app, but a change a person must decide still waits on the task page.
- The approval is therefore yours to build: show the person the change in your product — read the current value first, preview it with dryRun on a test account — and send it only after their yes.
- Any other app — Claude, Codex or another MCP host, or an app another workspace published — is never an own app: its ordinary changes wait for an admin or editor by default, irreversible changes always wait, and its raw writes are queued. A published app is your own app only in the workspace that registered it.
- GET /api/v1/me and GET /api/v1/capabilities say which rule a connection has (tools.writes, assembly.writesRun; and whether it is the workspace's own app).
Call logging
- Each API key and each OAuth connection has a Record tool and API calls switch on API & MCP (a workspace admin's), on by default.
- On: each tool and API call the connection makes is recorded in the workspace's audit log — tool name, account, outcome and time, never the values it sent, the platform's answer or a token. GET /api/v1/audit returns that connection's records.
- Off: those call records are not written. Always kept either way: the credit usage (GET /api/v1/usage), connecting and disconnecting, setting changes, and the approval queue's own records.
The integration path at a glance
- 1Authenticate — this page: authorization code with PKCE (S256 only) and resource=https://www.agentplanners.com/api/v1 for the REST API, sent on both the authorization request and the token request. Keep the newest refresh token: each refresh replaces it.
- 2Discover — GET /api/v1/me (the workspace and this connection), GET /api/v1/capabilities (what it may do, as JSON), GET /api/v1/accounts (the customer's connected accounts), GET /api/v1/tools?q=…&schema=1 and GET /api/v1/tools/{name} (the tools, each with the scope it needs and whether it runs at once or waits for a person).
- 3Invoke — POST /api/v1/tools/{name} with an Idempotency-Key: 200 ran, 202 waits for a person (poll GET /api/v1/requests/{id}, or wait for the write.decided webhook). Your own app's writes answer 200.
- 4Assemble — only where no tool exists and the person granted tools:raw (ticked by default): <family>__raw_request, sent through the customer's connected account. Reads run at once; a raw write runs at once for your own app and is queued for a person over any other app's connection.
- 5Follow up — GET /api/v1/requests, GET /api/v1/audit, GET /api/v1/usage and GET /api/v1/organization answer for this connection only.
- 6Verify — the six checks at the end of the REST API guide. A coding agent building the integration should read Build an integration (for coding agents).
An OAuth app or an API key?
Both reach the same REST API (https://www.agentplanners.com/api/v1) and MCP server (https://www.agentplanners.com/api/mcp). The difference is who holds the credential and how it got there.
- Use an OAuth app when people sign in to your product or internal tool: register it on API & MCP, and the people who use it approve it on the consent page — nobody copies a key.
- Use an API key for a script, a CI job or a server in your own workspace with no person present to sign in. Keep it in an environment variable, never in a repository.
- Either way the result is the same kind of connection: an approved app is listed on API & MCP under Connected apps with the same scopes, platform choice, write-approval setting, logging switch and audit trail as an API key, and it can be disconnected there.
- What differs is the write rule. Your own app (registered in this workspace) has no approval step. Any other OAuth connection's changes wait for an admin or editor by default, unless the admin who approved it chose Apply ordinary changes at once, and it always queues raw writes. An API key's ordinary writes apply at once inside the guardrails by default, unless it was created with Require approval for this key's write tools, and its raw writes are queued unless an admin pre-authorized it (Execute raw writes immediately). Permanent deletes and archives wait for a person on every credential except your own app. GET /api/v1/capabilities (tools.writes, assembly.writesRun) says which applies to a credential.
What the person sees on the consent page
- The app's name and where it will send them back. Claude, Claude Code, ChatGPT and Visual Studio Code are recognised by their exact callback address or client metadata document and shown as “Sends you back to Claude” (and so on). Any other app is marked Unverified app, with the name it gave itself in quotes — and, when it identifies itself with a metadata document, the host that serves that document — plus a warning to continue only if they started connecting it themselves.
- For an app another workspace published: Published by and that workspace's name in quotes, Unverified app until Agent Planners has verified it, and where it sends them back.
- The account they are signed in as, the workspace, and what the app connects to: the MCP server, the REST API or both. An app connects to one workspace; the workspace can be switched right there.
- What the app will be able to do, one checkbox per permission, in plain words — every permission ticked in advance, raw platform API access included; the person may untick any. A permission their role cannot grant is struck through with the reason.
- Platforms, when the app asks for platform tools: every platform connected to the workspace (including ones connected later), or only the ones they tick.
- Changes on your platforms, when the app asks to propose changes: Wait for approval is the default — each change the app proposes waits on API & MCP → Write approvals until an admin or editor approves it, and the person who connected it gets an email. A workspace admin can choose Apply ordinary changes at once instead; deletes and other changes a platform marks as a person's decision still wait for a person, and the workspace's guardrails still apply.
- For the workspace's own app (an app this workspace registered, connected to this workspace) there is no Changes on your platforms choice: one sentence says it is this workspace's own app and its changes apply at once, with no approval step — scopes, the platforms picked, workspace isolation and the guardrails still apply.
- For an app nobody has verified that returns to a website: a warning naming that website, only the reading permissions ticked in advance, no option to apply changes at once, and a box the person must tick to say they started the connection themselves. Anyone can register an app with any name, because MCP hosts need that; registering grants nothing.
- Allow access sends a one-time code back to the app; Cancel sends it an access_denied error. Nothing is granted before Allow access.
Permissions (scopes)
An app asks for scopes in the scope parameter, separated by spaces. An app that names none is asked for tasks:read tasks:write accounts:read tools:read tools:write tools:raw. Raw platform API access is on by default: the consent page ticks it like every other scope, and a client that asks for no scope gets it — if the approver may grant it. Words this server does not grant (openid, profile and the like) are ignored, never an error, and offline_access is accepted but changes nothing: every connection gets a refresh token.
| Scope | What it allows | Who can grant it |
|---|---|---|
| tasks:read | See the workspace's tasks, their plans, results and reports. | A workspace admin or editor |
| tasks:write | Start and follow up tasks; they run on the workspace's credits under its approval rules. | A workspace admin or editor |
| accounts:read | List the ad, analytics and store accounts connected to the workspace. | A workspace admin or editor |
| tools:read | Call the platforms' read tools — reports, settings, lists. | A workspace admin, on a paid plan |
| tools:write | Call write tools. By default each change waits for a person in the workspace to approve it, unless the approving admin chose Apply ordinary changes at once. The workspace's own app (registered in this workspace) has no approval step: its changes apply at once. | A workspace admin, on a paid plan |
| tools:raw | Call the platforms' own APIs through the workspace's connected accounts (the platform tokens stay in Agent Planners). Ticked by default. Reads run at once; a raw write waits for a person's approval over any app's connection except the workspace's own app, whose raw writes run at once. | A workspace admin, on a paid plan |
Build it into your own app: register it
AI agents (track 1) need nothing here — they register themselves when you sign in from them. To connect your own product or internal tool, a workspace admin registers it once:
- 1Open API & MCP → Your own OAuth apps and select Register an app.
- 2Give it a name and 1–10 redirect URIs, one per line.
- 3Choose Server app (a client secret, shown once — store it in your server's secret store; only a hash is kept) or Public app (no secret: a browser, desktop or mobile app that proves itself with PKCE alone).
- 4Choose who can connect it: Only this workspace (the default) or Any workspace on Agent Planners — see Publish an app to other workspaces below.
- 5Copy the client_id (and the secret) into your app, then run the flow below.
Publish an app to other workspaces
Publish an app when it is a product that serves many Agent Planners customers. Choose Any workspace on Agent Planners when you register it, or select Publish to any workspace on its row in API & MCP → Your own OAuth apps. A workspace admin decides both.
- What a customer sees: the same consent page as for any app, plus Published by and your workspace's name, the host it sends them back to, and Unverified app until Agent Planners verifies it. They choose the permissions, the platforms and — an admin — whether ordinary changes wait for approval (the default) or apply at once. Their workspace's admins get an email when it is connected.
- Where the connection lives: in the customer's workspace. It appears under their API & MCP → Connected apps, uses their credits, follows their approvals and guardrails, and they can disconnect it at any time. Their platform credentials never reach your app.
- What you see: on your app's row, how many connections it has and in how many workspaces — never which workspaces, and none of their data except what your tokens are allowed to read.
- Verification: to drop the Unverified label, contact support (https://www.agentplanners.com/support) from the publishing workspace. A verified app is shown under the name Agent Planners checked, unquoted, and its sign-in errors go straight back to it. Changing its name or redirect URIs removes the verification — it vouched for exactly those.
- Restrict it: Make private ends the connections of every other workspace at once (the confirm says how many); connections in your own workspace keep working. Remove ends every connection in every workspace for good.
- Rotate the secret (server apps): Rotate secret shows a new client secret once; the old one stops working at once, so your next token request — refresh included — must send the new one. Connections keep their tokens.
- Edit: the app's name and redirect URIs can be changed on its row; connections already made keep working.
What your app can and cannot do
A connection lets your app act in one customer's workspace, through the accounts that customer already connected in Agent Planners, inside the permissions and platforms the person approved.
- It can: call the tools its scopes allow (GET /api/v1/tools lists exactly those), and with tools:raw send <family>__raw_request calls to a platform's own API — Agent Planners attaches the customer's stored platform token, your app never sees it, and the request is bound to the account named in accountId.
- It can: read GET /api/v1/me, /capabilities, /organization, /accounts, /requests, /audit and /usage — for its own connection only — start tasks with tasks:write, and receive webhooks for the work it created.
- It cannot connect a platform or add an account, choose or preselect platforms, or widen its scopes — the person decides on the consent page; to change scopes or platforms they connect again, which makes a new connection.
- It cannot approve a write, its own or another's: a change that waits is decided by an admin or editor of the customer's workspace on API & MCP → Write approvals. In a workspace that did not register the app, raw writes always wait, and permanent deletes and archives always wait. In its own workspace there is nothing to approve: its writes apply at once — so your product asks the person first.
- It cannot see another app's work, which other workspaces connected it, or any platform credential.
Redirect URIs
- Matched exactly, as a whole string — never as a prefix or a wildcard.
- https on any host.
- http only on localhost, 127.0.0.1 or [::1]. A loopback redirect matches whatever port your app opened (RFC 8252); the path and query must still match.
- A private-use scheme in reverse-domain form, such as com.example.app:/callback, for a native app.
- No fragment, no user name or password, and never an address on Agent Planners' own site.
- At the token endpoint, a redirect URI that differs from a registered loopback one only by the loopback host — localhost, 127.0.0.1 or [::1], with the same port, path and query — is accepted.
Step 1 — send the person to /oauth/authorize
Open the authorization URL in the person's browser. Generate a fresh code_verifier for every sign-in — 43 to 128 characters of A–Z, a–z, 0–9 and - . _ ~ — and send its challenge, BASE64URL(SHA-256(code_verifier)), with code_challenge_method=S256; plain is refused. The example uses RFC 7636's own pair, whose code_verifier is dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk.
redirect_uri may be left out only when the app registered exactly one. resource decides where the token works: https://www.agentplanners.com/api/v1 for the REST API, https://www.agentplanners.com/api/mcp for the MCP server, or the origin https://www.agentplanners.com for a token valid on both. Send it here AND, with the same value, on the token request in step 3 — resource only on the token request is refused (invalid_target), and resource on neither gives a token for the MCP server only. state comes back unchanged (up to 2,048 characters; a longer one is refused). A parameter sent twice is refused.
OpenAPI-driven clients (Postman, Swagger UI, generated clients) must set resource on both requests as well — in Postman: OAuth 2.0 → Advanced, add resource to both the Auth Request and the Token Request.
Optional: platforms=google_ads,meta_ads (comma-separated tool families) pre-selects “Only these” on the consent page with the named platforms the workspace has connected. It is a suggestion — the person can change it — and an unknown or unconnected platform is ignored. Read what was granted from GET /api/v1/me afterwards.
An unknown client_id or a redirect_uri the app did not register is answered on our page and never redirected. A later error (a missing PKCE challenge, a wrong resource …) goes to the redirect URI with error, state and iss — at once for a workspace's private app when the person signing in is in that workspace, for a published app Agent Planners has verified and for the recognised products; for any other app the person sees the error first, with a Return link to the app.
GET https://www.agentplanners.com/oauth/authorize?response_type=code
&client_id=apc_0123456789abcdef01234567
&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
&code_challenge_method=S256
&scope=tasks%3Aread%20tasks%3Awrite%20accounts%3Aread
&state=f3a9c1d2
&resource=https%3A%2F%2Fwww.agentplanners.com%2Fapi%2Fmcp
(one URL, split over lines for reading)
For the REST API, the same URL with:
&resource=https%3A%2F%2Fwww.agentplanners.com%2Fapi%2Fv1
(or the origin, https%3A%2F%2Fwww.agentplanners.com, for a token valid on both)Step 2 — read the answer on your redirect URI
After the person decides, the browser is sent to your redirect URI with a 303. Check that state is the one you sent and that iss is https://www.agentplanners.com (RFC 9207) before you use the code.
The code is good for one exchange within 10 minutes. Exchanging the same code twice is refused, and the second attempt also ends the connection the first one created. A 503 (temporarily_unavailable — nothing was issued or changed) does not use the code up: retry the same code after Retry-After, within its 10 minutes.
HTTP/1.1 303 See Other
Location: https://app.example.com/oauth/callback?code=apo_ac_...&state=f3a9c1d2&iss=https%3A%2F%2Fwww.agentplanners.com
If the person selects Cancel:
Location: https://app.example.com/oauth/callback?error=access_denied&error_description=The+person+declined+to+connect+this+app.&state=f3a9c1d2&iss=https%3A%2F%2Fwww.agentplanners.comStep 3 — exchange the code at /oauth/token
A public app sends client_id and no secret (the first request below). A server app (a confidential client) authenticates with HTTP Basic: an Authorization: Basic header carrying client_id:client_secret (each part form-encoded first, then Base64), and does NOT also put client_secret in the body (the second request below). The token endpoint also accepts client_secret in the body next to client_id instead of Basic — one of the two, never both.
If step 1 sent redirect_uri, send the same value here — it is then required. Send resource again, the same value as step 1: the REST API needs it on both requests, and a resource that differs from step 1's is refused (invalid_target). The body is application/x-www-form-urlencoded as RFC 6749 specifies; JSON is accepted too.
A public app (no secret):
POST https://www.agentplanners.com/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=apo_ac_...
&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
&code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
&client_id=apc_0123456789abcdef01234567
&resource=https%3A%2F%2Fwww.agentplanners.com%2Fapi%2Fmcp
A server app (confidential client) asking for a REST API token — HTTP Basic, no client_secret in the body:
POST https://www.agentplanners.com/oauth/token
Authorization: Basic <Base64 of apc_0123456789abcdef01234567:your client secret>
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=apo_ac_...
&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
&code_verifier=<this sign-in's code_verifier>
&resource=https%3A%2F%2Fwww.agentplanners.com%2Fapi%2Fv1
The same request with curl (-u sends the Basic header; the secret comes from your secret store):
curl -X POST https://www.agentplanners.com/oauth/token \
-u "$AGENTPLANNERS_CLIENT_ID:$AGENTPLANNERS_CLIENT_SECRET" \
-d grant_type=authorization_code \
--data-urlencode "code=$code" \
--data-urlencode redirect_uri=https://app.example.com/oauth/callback \
--data-urlencode "code_verifier=$code_verifier" \
--data-urlencode resource=https://www.agentplanners.com/api/v1The token response
scope lists what the person actually approved — they can untick permissions, and anything their role cannot grant is left out (the tools:* scopes need an admin on a paid plan) — so read it rather than assume you received what you asked for. Every grant includes a refresh token. Keep both tokens on your server or in the operating system's secure storage, never in a URL or a log.
With a REST token, then call GET /api/v1/me and store the tokens under the connection it names — oauth.connectionId, with organization.id. Every consent creates a new connection, even for the same person, app and workspace, so a backend that serves many customers keys its tokens by connection.
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"access_token": "apo_at_...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "apo_rt_...",
"scope": "tasks:read tasks:write accounts:read"
}Refresh: each refresh token works once
- Each refresh answers with a new access token and a new refresh token; the refresh token you sent is spent. Save the new one before anything else.
- A refresh token expires after 30 days without use, and every refresh starts a new 30 days — a connection that refreshes at least once every 30 days does not expire.
- A spent refresh token presented again within 30 seconds, while the refresh token issued in its place is still unused, counts as a retry of a lost answer: that pair is withdrawn and a fresh pair is issued, so only one stays live. Any other reuse counts as theft: the whole connection ends and the answer is invalid_grant — the person has to connect again.
- A refused refresh (a bad scope, a server error) does not spend the refresh token you sent; retry with it. After a 500 or a temporarily_unavailable (503 with Retry-After), retry the same refresh token after the wait — it is still valid.
- invalid_grant on a refresh — the token was already used, expired or revoked, or the connection ended — is final: the person connects again. Presenting an old refresh token that was already rotated away ends the whole connection, so never keep or retry an older one.
- When to refresh: before expires_in runs out (when about 5 minutes are left), not after a 401. In a backend that serves many customers, take a per-connection lock, refresh, store the new pair in the same step, and release the lock — two workers must never refresh the same connection in parallel. Send the same resource and the same client authentication as at sign-in.
- scope on a refresh may keep or narrow the new access token's scopes, never widen them (invalid_scope). The refresh token always keeps the scopes the person approved.
- At each refresh, the person who approved the connection must still belong to the workspace with the role it needs — an admin for platform tools, an admin or editor for the rest. If not, the connection ends with invalid_grant. If the role cannot be confirmed right now and was last confirmed more than 24 hours ago, the answer is temporarily_unavailable (503): try again later — the connection is not ended.
- A connection ends 365 days after it was approved, however often it refreshes; the person connects again.
- Reconnecting is a new connection: each consent creates a new oauth.connectionId with its own tokens, and the earlier connection keeps working until it is revoked. After a reconnect, store the new tokens under the new connection and revoke the previous connection's refresh token (POST /oauth/revoke) so only one stays live.
- Failed sign-ins are throttled per address: 20 failed attempts within 5 minutes answer 429 “Too many failed authentication attempts”. That is an authentication failure, not a rate limit — fix the token instead of retrying it. Only unknown or malformed keys and tokens count: an expired, withdrawn or other-surface token Agent Planners issued answers 401 invalid_token and is not counted.
A public app:
POST https://www.agentplanners.com/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token=apo_rt_...
&client_id=apc_0123456789abcdef01234567
A server app (HTTP Basic, no client_secret in the body; the same resource as at sign-in):
POST https://www.agentplanners.com/oauth/token
Authorization: Basic <Base64 of apc_0123456789abcdef01234567:your client secret>
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token=apo_rt_...
&resource=https%3A%2F%2Fwww.agentplanners.com%2Fapi%2Fv1Revoke a token
Token revocation (RFC 7009), authenticated the same way as the token endpoint. A refresh token ends the whole connection — every token of it stops working and it shows as disconnected on API & MCP; an access token ends only itself. The answer is 200 with {} whether or not the token existed.
People can also disconnect any app themselves on API & MCP → Connected apps.
POST https://www.agentplanners.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded
token=apo_rt_...
&client_id=apc_0123456789abcdef01234567
A server app sends Authorization: Basic <Base64 of client_id:client_secret> instead of client_id in the body.Call the MCP server or the REST API
- Send the access token as Authorization: Bearer on https://www.agentplanners.com/api/mcp (MCP over Streamable HTTP) or https://www.agentplanners.com/api/v1 (REST). The tools the MCP server lists follow the connection's scopes, exactly as they do for an API key. Both answer CORS, so a browser app (or a browser-based MCP host) can call them with the person's own token — never with an API key or a client secret in the page.
- A token works only on the surface it was issued for: the MCP server (the default), the REST API when step 1 named /api/v1, or both when step 1 named the origin. If the authorization request leaves resource out, the token is for the MCP server only — a REST integration must send resource=https://www.agentplanners.com/api/v1 (or the origin https://www.agentplanners.com for both) on the authorization and the token request. A live token sent to the other surface answers 401 with the wrong_resource hint — on the REST API as code wrong_resource in the JSON body, on the MCP server in WWW-Authenticate and in the JSON-RPC error data (code wrong_resource, resource, tokenResource); a refresh cannot change it — connect again with the right resource.
- The MCP server negotiates the protocol version: it answers initialize with the version the client asked for when it supports it (2025-06-18, 2025-03-26 or 2024-11-05), otherwise 2025-06-18. It answers CORS on every response and OPTIONS with 204, so a browser-based MCP host works after the sign-in — with the person's token, never with cookies or a key in the page.
- REST scopes: GET /api/v1/accounts needs accounts:read (or any tools scope — a tools connection needs the account ids); GET /api/v1/tasks and GET /api/v1/tasks/{taskId} need tasks:read; POST /api/v1/tasks needs tasks:write.
- REST tools: GET /api/v1/tools, GET /api/v1/tools/{name}, POST /api/v1/tools/{name}, GET /api/v1/requests and GET /api/v1/requests/{id} need a tools scope (tools:read to read; tools:write for a write tool; tools:raw for <family>__raw_request); GET /api/v1/me answers for any valid token or key.
- Any valid token or key may also read GET /api/v1/capabilities (what this connection may do, as structured data), GET /api/v1/organization (the workspace, its plan, credits left and connected platforms), GET /api/v1/audit (this connection's audit trail) and GET /api/v1/usage (the credits it used). Each answers for this connection only — never another app's.
- A missing, expired or revoked token gets 401 with a WWW-Authenticate header naming the metadata below. On the REST API, a token without the needed scope gets 403 with error="insufficient_scope" and the scope to ask for.
- Requests are rate-limited per connection, like an API key's: 60 requests per 60 s (RateLimit-* headers on every answer); tool calls also share the workspace's 120 per 60 s, and task starts 20 per 10 min plus the plan's limit on concurrent tasks. A 429 carries Retry-After. GET /api/v1/capabilities (limits) has the numbers.
# AGENTPLANNERS_TOKEN = the access token (apo_at_…), read from your secret store
curl https://www.agentplanners.com/api/v1/accounts -H "Authorization: Bearer $AGENTPLANNERS_TOKEN"Call the tools over REST
The REST API calls the same platform tools as the MCP server — the same names (family__tool), scopes, platform choice, approvals, guardrails, credits and audit trail. Find a tool by what you want to do, read its JSON Schema, then run it with its arguments as the JSON body. Every call that runs is billed in credits like the same call over MCP — listing and describing tools 7 credits each; /me, /capabilities and /openapi.json are free.
Send an Idempotency-Key header with every write. The same key with the same arguments within 24 hours answers with the first result instead of writing twice — a queued write gives back the same requestId, one a person already decided answers 200 if it executed and 409 if it was rejected, expired or failed; a write that failed outright runs again; other arguments with the same key are a new write. Wait for the first answer before you retry.
A write that waits for a person answers 202 with a requestId and a statusUrl. Poll it with back-off — every 30 s at first, slowing to every 5 min — or list several at once with GET /api/v1/requests?status=pending, until its status is executed, failed, rejected or expired; stop at its expiresAt (an unanswered request expires after 24 hours). Or set a webhook and wait for write.decided. At most 50 writes can wait per workspace; one more answers 429 with Retry-After.
Read before you write, and test on a test account, never a live campaign. dryRun on a connection whose writes wait is queued like any write, so preview with the read tool instead (google_ads__get_tracking before google_ads__update_tracking). The full reference, with every endpoint and an OpenAPI document (https://www.agentplanners.com/api/v1/openapi.json), is the REST API guide.
BASE=https://www.agentplanners.com/api/v1
# AGENTPLANNERS_TOKEN = an access token issued for the REST API (or an API key), read from your secret store
# What this connection may do: scopes, platforms, whether writes wait (free)
curl "$BASE/me" -H "Authorization: Bearer $AGENTPLANNERS_TOKEN"
curl "$BASE/capabilities" -H "Authorization: Bearer $AGENTPLANNERS_TOKEN"
# The customer's connected accounts: id, family, provider, name (the id is a tool's accountId)
curl "$BASE/accounts" -H "Authorization: Bearer $AGENTPLANNERS_TOKEN"
# Find a tool by what you want to do (free; only the tools this connection may call)
curl "$BASE/tools?q=update+tracking+url+suffix&kind=write" -H "Authorization: Bearer $AGENTPLANNERS_TOKEN"
# Its documentation, JSON Schema and whether this connection may call it (free)
curl "$BASE/tools/google_ads__update_tracking" -H "Authorization: Bearer $AGENTPLANNERS_TOKEN"
# Read the current value first (a read runs at once)
curl -X POST "$BASE/tools/google_ads__get_tracking" \
-H "Authorization: Bearer $AGENTPLANNERS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"accountId":"<id from /accounts>","level":"campaign","ids":["111222333"]}'
# Then the change: one UTM parameter merged into the campaign's final URL suffix, as a dry run (a test account)
curl -X POST "$BASE/tools/google_ads__update_tracking" \
-H "Authorization: Bearer $AGENTPLANNERS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: utm-suffix-campaign-111222333-v1" \
-d '{"accountId":"<id from /accounts>","level":"campaign","ids":["111222333"],"finalUrlSuffixSet":{"utm_source":"google"},"dryRun":true}'
# 200 {"ok":true,"result":{"ok":true,"tool":"google_ads__update_tracking","kind":"write","accountId":"…","result":{...}}} it ran (a dry run: the preview)
# 202 {"ok":true,"queued":true,"requestId":"rwq_3f9a1c2b4d5e","statusUrl":"/api/v1/requests/rwq_3f9a1c2b4d5e"} it waits for a person
# After a 202: the person's decision
curl "$BASE/requests/rwq_3f9a1c2b4d5e" -H "Authorization: Bearer $AGENTPLANNERS_TOKEN"
# {"ok":true,"result":{"requestId":"rwq_3f9a1c2b4d5e","status":"pending_approval",...}}REST status codes
| Status | Meaning | What to do |
|---|---|---|
| 200 | The tool ran (or the read answered). The body is { ok: true, result: { ok, tool, kind, accountId, result } } — the tool's own answer is result.result. | Use the result. A notices array, when present, carries extra lines such as low credits. |
| 202 | A write waits for a person in the workspace; nothing has changed on the platform yet. The body is { ok: true, queued: true, requestId, statusUrl } — for a raw write too. | Poll GET /api/v1/requests/{id} with the requestId (back off from 30 s to 5 min) until it is executed, failed, rejected or expired, or wait for write.decided. |
| 400 | The body is not a JSON object of arguments. | Fix the request; retrying it unchanged fails again. |
| 401 | The token or key is missing, expired or revoked; a WWW-Authenticate header names the metadata. A token issued for the MCP server answers code wrong_resource with the resource to request. | Refresh the access token once and retry; if it still fails, connect again. On wrong_resource, connect again with resource=https://www.agentplanners.com/api/v1. |
| 402 | The workspace does not have enough credits for this call. | Do not retry. Ask the workspace to top up; the message says how many credits the call needs. |
| 403 | This connection may not call it: a missing scope (WWW-Authenticate error="insufficient_scope"), the plan, the platforms or platform tools the person allowed, or autoApprove on a connection whose changes wait (POST /api/v1/tasks: code auto_approve_not_allowed, no task created). | Do not retry. Ask for the scope or platform on a new connection; GET /api/v1/capabilities shows what is allowed. |
| 404 | No such tool, or no such request in this workspace — or one this credential did not queue (another live connection of the same OAuth app in the same workspace may read it). | Check the name with GET /api/v1/tools; poll a request with the key or token that queued it. |
| 409 | No account of the tool's platform is connected in the workspace or exposed to this connection; or a write a person already decided was sent again with its Idempotency-Key (rejected, expired or failed); or a task's Idempotency-Key was reused with another goal (code idempotency_key_reused). | Ask the workspace to connect that platform (or the person to reconnect with it); for a decided write or a new goal, use a new key. |
| 413 | The body is larger than 1 MB. | Send fewer items per call. |
| 422 | The tool ran and answered with an error, or refused the arguments; the error says why. It includes a missing, ambiguous or unknown accountId (the error lists the candidates as id (name)) and a raw read the platform answered with a 4xx (result.status, result.error). | Fix the arguments the error names; GET /api/v1/tools/{name} shows the schema. |
| 429 | Rate limited (this connection, or the workspace's tool calls), or 50 writes already wait for approval in the workspace; Retry-After says when to try again. “Too many failed authentication attempts” is an authentication failure instead: 20 failed sign-ins from one address within 5 minutes. | Wait Retry-After, then retry with the same Idempotency-Key. On the failed-attempts answer, fix the token first. |
| 500 | An unexpected server error; the body still carries { ok: false, error } and the CORS headers. A write may or may not have reached the platform. | Retry a read; before resending a write, check GET /api/v1/requests and GET /api/v1/audit, then retry with the same Idempotency-Key. |
| 503 | Something the answer depends on (the database, the workspace's plan or the connection's policy) could not be read right now; nothing ran (it fails closed) — POST /api/v1/tasks answers code write_policy_unreadable. Retry-After says when. | Retry after Retry-After with the same Idempotency-Key. |
Discovery: the metadata documents
- https://www.agentplanners.com/.well-known/oauth-protected-resource/api/mcp — the MCP server's protected resource metadata (RFC 9728). The bare /.well-known/oauth-protected-resource answers the same.
- https://www.agentplanners.com/.well-known/oauth-protected-resource/api/v1 — the REST API's.
- https://www.agentplanners.com/.well-known/oauth-authorization-server — the authorization server metadata (RFC 8414): the endpoints, the scopes, code_challenge_methods_supported ["S256"], client_id_metadata_document_supported and authorization_response_iss_parameter_supported.
- The issuer is https://www.agentplanners.com. An unauthenticated call to the MCP server is answered like this (the REST API names its own document):
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://www.agentplanners.com/.well-known/oauth-protected-resource/api/mcp", scope="tasks:read tasks:write accounts:read tools:read tools:write tools:raw"How a client identifies itself
- A registered client_id (apc_…): an app a workspace admin registered on API & MCP, or one registered through Dynamic Client Registration.
- Dynamic Client Registration (RFC 7591): POST JSON to /oauth/register with 1–10 redirect_uris and optionally client_name and token_endpoint_auth_method — none (the default: a public client), client_secret_basic or client_secret_post. Registering grants nothing; a person still approves. A confidential registration's client_secret appears in the answer once, and a registration no token was ever issued for is forgotten after 3 days.
- Client ID Metadata Documents: a client_id that is an https URL with a path (on the default port) is fetched when a person opens the consent page — never by the token endpoint — with no redirects followed, at most 64 KB, within 5 seconds. It must be a JSON document whose client_id equals that URL, with redirect_uris and no secret (token_endpoint_auth_method none). It is cached as its Cache-Control says, between 5 minutes and 24 hours, and forgotten after 30 days without a token issued for it.
POST https://www.agentplanners.com/oauth/register
Content-Type: application/json
{"client_name": "Example MCP host", "redirect_uris": ["http://127.0.0.1:33418/callback"], "token_endpoint_auth_method": "none"}
HTTP/1.1 201 Created
{"client_id": "apc_...", "client_id_issued_at": 1791158400, "client_name": "Example MCP host", "redirect_uris": ["http://127.0.0.1:33418/callback"], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"]}Lifetimes
| What | Lifetime |
|---|---|
| Authorization code | 10 minutes, one exchange |
| Access token | 1 hour (expires_in 3600) |
| Refresh token | 30 days without use; replaced at every refresh |
| Connection | 365 days from approval, however often it refreshes |
| Retry window for a spent refresh token | 30 seconds |
| Consent page | 10 minutes from opening |
| Self-registered client no token was issued for | 3 days |
| Client ID Metadata Document cache | 5 minutes to 24 hours, per Cache-Control; forgotten after 30 days without a token |
Errors
| error | Status | When |
|---|---|---|
| invalid_request | 400 | A parameter is missing, malformed or sent twice; PKCE is missing; client credentials were sent both as Basic and in the body. |
| invalid_client | 401 | Unknown client_id, a wrong secret, or a secret sent by a public client. |
| invalid_grant | 400 | The code is invalid, expired, already used or issued to another client; redirect_uri is missing (step 1 sent one) or does not match; the PKCE code_verifier does not match; the refresh token is expired, revoked or already used (the connection is ended); the approver can no longer grant the connection; the connection is a year old. |
| invalid_scope | 400 | A refresh tried to widen the scopes. |
| invalid_target | 400 | resource is not the MCP server, the REST API or the origin, or does not match the authorization — including a resource sent on the token request when the authorization request had none. |
| unsupported_grant_type | 400 | grant_type is not authorization_code or refresh_token. |
| unsupported_response_type | to the redirect URI | response_type is not code. |
| access_denied | to the redirect URI | The person selected Cancel, or approved no permission. |
| invalid_redirect_uri | 400 | A registration's redirect_uris are missing, more than 10, or break the redirect rules above. |
| invalid_client_metadata | 400 | A registration is not a JSON object, or names an unsupported token_endpoint_auth_method, grant type or response type. |
| temporarily_unavailable | 429 or 503 | Too many requests from one address, or registration is paused for the day (429, with Retry-After); or, during an outage, the token, revoke or register endpoint could not reach its storage, or a refresh could not re-check the approver's role right now (503, with Retry-After) — retry the same request after that. A refused refresh does not spend the refresh token. |
| server_error | 500 or 503 | Something failed on our side; try again — a refresh with the same refresh token, which it did not spend. |
Security notes
- Authorization code with PKCE (S256) is the only flow, for public and server apps alike — no implicit flow, no password grant, no client credentials grant.
- Tokens, codes and client secrets are stored only as SHA-256 hashes; a client secret is shown once.
- Redirect URIs are matched exactly, and a redirect the app did not register is never followed.
- Every authorization response carries iss (RFC 9207), and every token is bound to the resource it was issued for (RFC 8707).
- The consent page cannot be embedded in another site's frame, Allow access becomes clickable only after the page has been on screen for a moment (so a click aimed at another window cannot approve it), and an approval must be posted from Agent Planners itself, once.
- When an app is connected, the workspace's admins get an email naming the app, the person who approved it and what it may do, with a link to disconnect it.
- Ad-platform credentials never leave Agent Planners: a connected app receives results, never a Google, Meta or store token.
- Approving, declining and ending a connection are written to the workspace's audit log whatever the logging switch says, and the credits a connected app uses are charged to the workspace it connected to.
- The workspace's own app is decided on the server from the app's registration and the workspace the person approves in — at the consent decision and again at the code exchange — never from anything the app sends.
Frequently asked questions
- Do I still need an API key?
- Not for your own system: an OAuth app lets people sign in instead. An API key remains the simplest credential for a script, a CI job or a server in your own workspace where no person is present to sign in. AI agents such as Claude or Codex need no app at all — they sign in by themselves (see Connect Agent Planners to Claude, Codex, Grok and Muse).
- Does my own app's change wait for approval?
- No. An app your workspace registered, connected to your workspace, is the workspace's own app: its writes apply at once — raw requests and deletes included — inside the scopes, platforms and guardrails the person approved. So show the person the change in your product and send it only after their yes. In another workspace that connects your published app, its changes wait for that workspace's approval by default.
- Which plan do I need?
- Any plan can connect an app for tasks and connected accounts. Direct platform tools (tools:read, tools:write, tools:raw) need a paid plan and a workspace admin's approval — the same rule as a tools-mode API key.
- Why did a connection end on its own?
- A refresh token was used twice outside its 30-second retry window, the authorization code was used twice, the person who approved it left the workspace or lost the role it needs, the app was removed by the workspace that registered it, the workspace that publishes it made it available to itself only, the app disconnected itself, or the connection reached 365 days — API & MCP → Connected apps shows which. A connection whose refresh token goes 30 days unused also stops working. Either way, connect again from the app.
- Can another product update my campaigns through Agent Planners — for example a link-management app that keeps my UTM parameters current?
- Yes, if its publisher made it available to every workspace and you connect it: you approve it on the consent page in your own workspace, choose which permissions and platforms it gets, and can disconnect it any time on API & MCP. It then calls the same platform tools as Claude or ChatGPT would, through the REST API with your connection's token. Its changes wait for a person in your workspace unless your admin chose to apply ordinary changes at once, and it never receives your platform credentials.
- How does my server know whether a write was applied?
- The REST API answers 200 when the tool ran and 202 when the write waits for a person, with a requestId; GET /api/v1/requests/{id} returns the decision — executed, failed, rejected or expired (pending_approval and approved while it waits or runs). Send an Idempotency-Key with every write so a retry never writes twice: within 24 hours the same key and arguments return the first answer, and a write a person already decided answers 200 if it executed and 409 if it was rejected, expired or failed.
- Can my app be told instead of polling?
- Yes. On API & MCP, under your OAuth app, set a webhook: Agent Planners POSTs write.queued, write.decided and task.finished for the work of every connection of your app — in every workspace that connected it, including after a connection ended, each event naming the workspace (organizationId) and the connection (connectionId, what GET /api/v1/me returns) — signed with a secret shown once. A write applied at once sends no write.* event: its 200 is the answer. Each delivery is tried up to 3 times (AgentPlanners-Attempt says which), and a rotated signing secret applies at once, so accept both secrets while you switch. The event list, the payload and the verification code are in the REST API guide's Webhooks section. A connection never carries a webhook of its own: the customer's workspace cannot point your app's events elsewhere.
- What happens when a customer connects my app again?
- They get a new connection — a new oauth.connectionId with its own access and refresh tokens — and the earlier one keeps working until it is revoked. Store tokens per connection, and after a reconnect revoke the previous connection's refresh token at /oauth/revoke. Reconnecting is also the only way to change a connection's scopes or platforms: your app cannot widen them, preselect platforms or connect a platform itself.
- Can the app change my campaigns without asking?
- Another app — an AI agent, or an app another workspace published — not with the default setting: each change it proposes waits on API & MCP → Write approvals for an admin or editor. A workspace admin can choose to apply ordinary changes at once; deletes and other changes a platform marks as a person's decision still wait for a person, inside the workspace's guardrails. The workspace's own app (registered by this workspace) is the exception: it has no approval step.
- Does the app see my Google, Meta or Shopify credentials?
- No. Platform credentials stay in Agent Planners; the app holds only its own Agent Planners tokens and receives results.