API Tokens

Create org-scoped tokens for CI and AI agents — draft content by default, opt-in scopes for publish, delete, social drafts, and site setup.

Updated 13d ago

In short

Organization → API tokens creates bearer tokens for automation. Default scopes list sites and read or write draft pages. Opt in to delete, publish, social drafts, create sites, or manage collections when creating the token.

When to use API tokens

Use tokens when you want tools such as Cursor, GitHub Actions, or internal scripts to:

List sites and pages in your organization
Create or update draft MDX content
Optionally create sites, collections, publish, delete, or draft social posts — when you grant those scopes

Tokens are not a replacement for signing into the dashboard. They are for machine access with a narrow scope.

Creating a token

Open Organization → API tokens.
Click Create token.
Enter a name you will recognize later (for example CI docs sync).
Choose scopes (see below). Destructive scopes are off by default.
Optionally limit to specific sites — required for delete and publish scopes (unless you are an org admin).
Copy the secret when shown — it is displayed only once.

Store the token in your password manager or CI secrets (for example AVEIRO_API_TOKEN).

Scopes

Scope	Allows
sites:read	List sites the token can access (default)
sites:write	Create new sites
collections:write	Create collections (folders)
content:read	Read draft page content and metadata (default)
content:write	Create and update draft pages (default)
content:delete	Delete pages and collections
publish:write	Publish or unpublish site content
audience:write	Add email subscribers via API
social:write	Draft and revise social posts; list accounts and media (no approve/publish)
newsletter:read	List past email campaigns and read their content and analytics
newsletter:write	Draft and revise email campaigns (no send/schedule)

Default token: sites:read, content:read, content:write. Delete and publish require limiting the token to specific sites (non-admins).

Who can grant which scopes

When you create a token, Aveiro only lets you select scopes your member permissions allow:

Scope	Requires capability
content:write	Docs update
audience:write	Audience manage
social:write	Audience manage
newsletter:read	Audience manage
newsletter:write	Campaign create

Owners and admins can grant every scope. Members without the matching capability see a clear error if they try to include a scope they cannot grant.

API endpoints

All routes live under /api/v1 on your platform host (for example https://help.aveiro.app).

Endpoint	Purpose
GET /api/v1/me	Token name, org, scopes, and allowed site IDs
GET /api/v1/sites	List accessible sites
GET /api/v1/templates	List marketplace templates for cloning (sites:read)
POST /api/v1/sites	Create a site — optional template slug clones marketplace layout (sites:write)
GET /api/v1/sites/{siteId}/collections	List collections
POST /api/v1/sites/{siteId}/collections	Create a collection
DELETE /api/v1/sites/{siteId}/collections/{id}	Delete a collection (content:delete)
GET /api/v1/sites/{siteId}/pages	List draft pages
GET /api/v1/sites/{siteId}/pages/by-path?path=...	Fetch one page by path
POST /api/v1/sites/{siteId}/pages	Create a draft page
PATCH /api/v1/sites/{siteId}/pages/{contentId}	Update draft content
POST /api/v1/sites/{siteId}/reorder	Reorder, move, or sort pages (content:write)
DELETE /api/v1/sites/{siteId}/pages/{contentId}	Soft-delete a page (content:delete)
POST /api/v1/sites/{siteId}/publish	Publish dirty drafts (publish:write)
POST /api/v1/sites/{siteId}/unpublish	Hide site or unpublish pages (publish:write)
GET /api/v1/sites/{siteId}/media	List site media images (content:read)
POST /api/v1/sites/{siteId}/media/upload	Prepare a signed upload for site media (content:write)
GET /api/v1/sites/{siteId}/changes	List dirty drafts awaiting review
GET /api/v1/social/accounts	List connected social accounts (social:write)
GET/POST /api/v1/social/posts	List or create social drafts (social:write)
GET/PATCH /api/v1/social/posts/{postId}	Read or revise a social draft (social:write)
GET/POST /api/v1/social/media	List or register social media assets (social:write)
GET /api/v1/social/org-media	Browse org media storage — dashboard uploads (social:write)
POST /api/v1/social/media/generate	AI-generate social images — up to four aspectRatios per call (social:write)
GET/POST /api/v1/campaigns	List or draft email campaigns (newsletter:read / newsletter:write)
GET/PATCH /api/v1/campaigns/{campaignId}	Read or revise a draft campaign (newsletter:read / newsletter:write)
GET /api/v1/campaigns/{campaignId}/analytics	Send, open, click, and unsubscribe metrics (newsletter:read)

Social routes are documented in the Social API reference. Platform guide: Social agents and API. Newsletter routes are documented in the Newsletter API reference. Platform guide: Audience agents and API. Send the token as Authorization: Bearer av_live_… on every request. Valid page writes can include an advisory recommendations array when content reads off-dialect — button rows, hand-rolled heroes, or bare internal link lists. The draft still saves; each entry suggests a rewrite toward Aveiro's editorial dialect. Agents connected over MCP should call aveiro_authoring_guide before their first write. See the Site media API for image uploads.

Idempotency

When creating pages with POST, pass an Idempotency-Key header so retries do not create duplicates. Reusing the same key with a different body returns a conflict error.

Revoking tokens

Open the token row menu → Revoke. Revocation is immediate — automations using that token stop working. Admins see every active token in the organization.

Workflow with the editor

Automation writes or updates draft content via the API.
Open the page in the editor (each API response includes an editor_url) to review, or use publish:write to go live from CI.
Check GET …/changes to see which pages still have unpublished edits.

Members and permissions — who can create tokens
Publishing settings vs content — what publish covers
Publishing pages — page-level publish

Members and Permissions

Aveiro MCP server

API Tokens

API Tokens

When to use API tokens

Creating a token

Scopes

Who can grant which scopes

API endpoints

Idempotency

Revoking tokens

Workflow with the editor

Related guides

When to use API tokens

Creating a token

Scopes

Who can grant which scopes

API endpoints

Idempotency

Revoking tokens

Workflow with the editor

Related guides