Authentication

Bearer sessions, personal access tokens, and workspace headers.

Every authenticated request sends a bearer token:

Authorization: Bearer <token>

You can use a session token from sign-in, or a personal access token (PAT) created for CI and scripts.

Session token (humans and apps)

curl -X POST https://api.dunsocial.com/api/auth/sign-in/email \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com","password":"your-password"}'

Use the returned token on later requests. Sign out with POST /api/auth/sign-out. Check the current session with GET /api/auth/get-session.

Email verification is required for new accounts. Sessions last about 30 days.

Personal access tokens (CI and agents)

PATs are best for automation. Create one while signed in (Settings → CLI in the app, or the API):

curl -X POST https://api.dunsocial.com/api/cli/tokens \
-H "Authorization: Bearer YOUR_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "name": "github-actions",
  "workspaceId": "YOUR_WORKSPACE_ID",
  "scopes": ["posts:schedule", "posts:publish", "drafts:write"],
  "expiresInDays": 90
}'

The response includes the raw token once. Store it like a password. Format: dun_pat_<prefix>_<secret>.

PATs are bound to a single workspace. Send that workspace in X-Workspace-Id. A mismatch returns 403.

Available scopes

Scope	What it allows
`workspace:read`	Read workspace and members
`posts:read`	List and get posts
`posts:schedule`	Schedule posts and threads
`posts:publish`	Publish now
`posts:delete`	Cancel or delete posts
`drafts:write`	Create, update, delete drafts
`media:read` / `media:write`	Gallery and uploads
`memory:read` / `memory:write`	Memories and collections

Use scopes: ["*"] for all scopes. Empty scopes fall back to a small CI default set.

PATs cannot call AI, webhooks management, notifications, billing, or CLI token management. Those need a session.

Workspace header

Most content routes need a workspace:

curl https://api.dunsocial.com/api/posts \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID"

You must be an active member. Suspended members get 403.

The CLI uses a device-code flow (POST /api/cli/auth/start and poll). That is covered in the CLI install guide. The result is still a normal session bearer token.

List and revoke PATs

Method	Path	Notes
`GET`	`/api/cli/tokens`	Metadata only (no secrets)
`DELETE`	`/api/cli/tokens/:id`	Revoke

Connecting MCP assistants

Assistants connect with OAuth — paste https://api.dunsocial.com/api/mcp and approve in the browser. See the MCP guide. Do not mint long-lived MCP tokens for new setups.

A legacy POST /api/user/mcp-token endpoint still exists for older clients, but Settings → MCP no longer exposes it. Prefer OAuth.