Scoped Agent Access

Use an agent key when an automated process should publish or schedule without receiving the owner credential. The hosted service enforces scopes and destination policy before it stages media, reads schedules, or calls Meta.

Create a key

Run key-management commands from the owner's normal sfeed session:

sfeed destinations
sfeed agents create --name codex --scopes publish,schedule --destinations <id>,<id>

Use a fixed destination list for the narrowest policy. Use --all-destinations only when the process should also gain access to destinations connected in the future:

sfeed agents create --name codex --scopes publish,schedule --all-destinations

The command prints SFEED_USER_ID and SFEED_AGENT_TOKEN exactly once. sfeed stores only a hash of the token.

Run an isolated agent

SFEED_USER_ID=<owner-user-id> \
SFEED_AGENT_TOKEN=<one-time-token> \
sfeed mcp

Pass these values through the agent runtime, process manager, or MCP configuration. Do not put the scoped token in the owner's ~/.sfeed/.env.

Scope aliases

• read -- list allowed destinations and inspect their scheduled posts
• publish -- list allowed destinations, stage media, and publish immediately
• schedule -- list allowed destinations, stage media, read schedules, and create or change scheduled posts
• all -- every agent data-plane scope

Canonical scopes are also accepted: destinations:read, publish:write, schedule:read, schedule:write, and media:write.

Owner-only operations

Agent keys cannot connect or revoke Meta accounts, manage billing, create or revoke other keys, read the audit stream, or mint signed dashboard and preview URLs. Those operations require the owner credential.

Security boundary

An environment variable is not a security boundary. A process that can read the owner's ~/.sfeed/tokens.json can recover the owner credential and bypass the agent key's scopes and destination policy.

For an untrusted agent, use a separate OS user, container, or sandbox that cannot read the owner's sfeed home directory. Give that runtime only the two scoped environment variables and the files it needs for its work.

Rotate and audit

sfeed agents list
sfeed agents revoke <key-id>
sfeed agents create --name codex --scopes publish,schedule --destinations <id>,<id>

sfeed audit
sfeed audit --json

Rotation is revoke then create. Revocation takes effect on the next hosted request. The owner audit stream records content-free key, authorization, publish, and schedule events for 365 days. It never contains post content, media URLs, provider credentials, or raw agent tokens.

Retry behavior

The CLI automatically sends an idempotency key for immediate publishing. An identical retry replays the first completed response without another provider call. If a previous provider call may still be unresolved, sfeed returns a conflict with may_have_published instead of risking a duplicate post.

Configure the MCP server

Back to Docs