Authentication

Every request carries an API key as a bearer token.

curl https://beta.sparkfeed.dev/api/v1/feeds \
  -H "Authorization: Bearer sfk_live_..."

Create a key under Developer → API Keys in the app. The secret is shown once.

Scopes

A key carries scopes, and each endpoint requires one. A key without it gets a 403 naming the scope it needs, rather than an empty result.

Scope	Grants	On a new key
mcp	Use the API at all	yes
workspace:read	Read folders, feeds and workspace stats	yes
articles:read	Search and read articles	yes
articles:write	Mark read, set favourites	yes
feeds:write	Add feeds, create folders, move feeds	no

Write endpoints need a scope new keys do not have

A key created from Developer → API Keys gets the four scopes above marked yes. It does not get feeds:write, so POST /feeds, POST /folders and PATCH /feeds/{feed_id} will return 403 until the key is minted with that scope explicitly.

The demo key

sfk_demo_public works against demo.sparkfeed.dev and holds read scopes only. It is what the Send buttons in these docs use, so you can try every read endpoint without signing up.

Failing requests

A missing or invalid key returns 401 with a WWW-Authenticate header pointing at this deployment’s resource metadata, so a client can discover how to authenticate rather than guess.