Menu Ur Next DoorAPI Docs Get an API key

Scopes and permissions

The four API key scopes (content, media, schedule, read), which endpoints each one unlocks, and which combination to give each kind of tool.

View as Markdown

Scopes decide what a key may do. You choose them when you create the key. Give each tool only the scopes it needs: if the key ever leaks, it can do less harm.

The four scopes

ScopeAllowsEndpoints
contentCreating content, published now or scheduledPOST /posts, /questions, /polls, /mcqs, /communities, /services, /jobs
mediaUploading imagesPOST /media
scheduleManaging items you already scheduledGET /scheduled, POST /scheduled/{type}/{id}/reschedule, POST /scheduled/{type}/{id}/publish, DELETE /scheduled/{type}/{id}
readLookups a tool needs to fill in idsGET /communities/postable, /service-categories, /job-options, /geo, /community-icons

Paths are relative to https://urnextdoor.com/api/v1.

Two endpoints need no particular scope, only a valid key: GET /me (who am I) and GET /usage (today's quota). GET /openapi.json is public and needs no key at all.

Scheduling a new item only needs content: add scheduled_at to the create. The schedule scope is for changing items after they are scheduled.

ToolScopes
AI agent that writes and publishes posts with images (Claude Code, Codex CLI)content, media, read
The same agent, also allowed to move or cancel scheduled postscontent, media, read, schedule
ChatGPT custom GPTcontent, read (add media only for very small images, see ChatGPT Actions)
Zapier or n8n flow that publishes from a spreadsheetcontent (add read if it looks up communities)
A dashboard that only lists what is scheduledschedule
Exploring the API in Postmanread first; add the others when you are ready to publish

When a scope is missing

The request answers 403 with the code insufficient_scope and names the missing scope:

JSON
{
  "ok": false,
  "error": "This API key does not have the \"content\" scope. Create a key that includes it.",
  "code": "insufficient_scope",
  "request_id": "a1b2c3d4e5f60718"
}

You cannot add scopes to an existing key. Create a new key with the scopes you need, switch your tool to it, and revoke the old one.

Scopes are not the only check

A scope says what kind of action a key may attempt. The API still checks your own permissions on every request, exactly as the website does. A key with content cannot post into a community where you are not an editor (or above): that answers 403 forbidden. Use GET /api/v1/communities/postable to list the communities you can post in.

Next steps

Last updated