Authentication — sharetodos developers

API keys

Create an API key at sharetodos.com/developers. Each key is tied to your account and inherits your permissions.

Keys are shown once. Copy your key immediately after creating it — it cannot be retrieved again. If lost, revoke it and create a new one.

Keys follow this format:

sk_live_a1b2c3d4e5f6...  ← 64 hex characters after the prefix

Prefix	Environment	Description
`sk_live_`	Production	Reads and writes real data
`sk_test_`	Test	Sandbox environment (coming soon)

Sending your key

Pass the key in the X-API-Key request header:

curl https://api.sharetodos.com/v1/me \
  -H "X-API-Key: sk_live_your_key_here"

For all mutating requests, set Content-Type: application/json alongside the key:

curl -X POST https://api.sharetodos.com/v1/actions/add \
  -H "X-API-Key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"items": ["buy milk"], "list": "Shopping"}'

Verifying your key

Call GET /v1/me to confirm your key is working and see what scopes it has:

curl https://api.sharetodos.com/v1/me \
  -H "X-API-Key: sk_live_your_key_here"

{
  "data": {
    "id": "user_abc123",
    "email": "you@example.com",
    "name": "Your Name",
    "username": "yourname",
    "scopes": ["lists:read", "lists:write", "items:read", "items:write", "profile:read"]
  },
  "error": null
}

Scopes

API keys carry scopes that control what they can do. All keys currently receive the full scope set below — granular key scopes are on the roadmap.

Scope	Permissions
`lists:read`	Read lists and their metadata
`lists:write`	Create lists, invite members, share
`items:read`	Read items in any accessible list
`items:write`	Add, complete, and remove items
`profile:read`	Read your own profile (`/me`)

Security recommendations

Store keys in environment variables, never in source code
Use separate keys per environment (local, staging, production)
Rotate keys periodically or immediately if you suspect a leak
Give each integration its own key so you can revoke independently
Never log or transmit keys in plaintext