Public share links

A share link is an unlisted public URL for a single resource. Anyone holding the link can view it without a Flambe account — which makes the token a secret.

Minting

curl -X POST https://api.flambe.dev/api/share-links \
  -H "Authorization: Bearer $FLAMBE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "resource_type": "recipe", "resource_id": "9b8a7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d" }'

{
  "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
  "token": "Yk9sTnFXcmY",
  "resource_type": "recipe",
  "resource_id": "9b8a7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
}

The public URL is https://flambe.dev/share/{token}.

resource_type is one of recipe, collection, mealplan, grocerylist.

Resolving

GET /api/shared/{token} is the one read endpoint that needs no authentication — it is what renders the page for a recipient with no account.

curl "https://api.flambe.dev/api/shared/Yk9sTnFXcmY"

An unknown or revoked token returns 404.

Saving a shared resource

POST /api/shared/{token}/save copies the resource into the caller's own library. Unlike resolving, this does require authentication — it has to know whose library to write to.

Revoking

curl -X DELETE "https://api.flambe.dev/api/share-links/$SHARE_LINK_ID" \
  -H "Authorization: Bearer $FLAMBE_TOKEN"

Note the path takes the share link's id, not its token.

Revocation is immediate: the URL stops resolving. A page already open keeps whatever it has already loaded — revoking does not reach into a browser that has the content in memory.

Treat the token as a credential

• Anyone with the link can read the resource. There is no second factor.
• Links are excluded from sitemap.xml and disallowed in robots.txt, so they are not indexed — but that is not a security boundary. A link pasted into a public channel is public.
• Revoke rather than relying on obscurity once a link has served its purpose.

Share links vs households

See Households for the second.