API Keys

Creating an API Key

1. Select an app in the dashboard
2. Enter a key name and select a scope in the “API Keys” section
3. Click “Create” — the key is shown only once

Caution

API keys are displayed only once at creation time. Be sure to copy and store them in a safe place.

Scopes

Scope	Use Case	Allowed Operations
subscribe_only	Frontend embedding	Subscribe/unsubscribe only
notify	Server-side notification sending	Notification sending + subscription operations
full	Management	All operations (including app info and statistics)

Usage Examples

User's browser (frontend)
  └─ subscribe_only key → /api/v1/subscriptions (POST) / /api/v1/apps/:appId/subscriptions (POST/DELETE)

Your server (backend)
  └─ notify key → /api/v1/notify (POST)

CI / admin scripts
  └─ full key → all endpoints

Tip

The subscribe_only key is safe to include in frontend source code. Since it can only register/unregister subscriptions, it cannot be used for unauthorized notification sending.

Authentication

API keys are sent via the Authorization: Bearer header.

curl -H "Authorization: Bearer pk_your_key_here" \
  https://api.todoke.dev/api/v1/notify \
  -H "Content-Type: application/json" \
  -d '{"title":"test","body":"test"}'

Key Format

pk_a1b2c3d4e5f6...  (64-character hex string)

Scope × Endpoint Permission Matrix

The scopes that can call each endpoint.

Endpoint	subscribe_only	notify	full
POST /api/v1/subscriptions (for SDK)	✅	✅	✅
POST / DELETE /api/v1/apps/:appId/subscriptions	✅	✅	✅
GET /api/v1/vapid-public-key	✅	✅	✅
GET /api/v1/stats	—	✅	✅
POST /api/v1/notify · /notify/batch	—	✅	✅
POST /mcp (MCP endpoint)	—	✅	✅
MCP list_api_keys / create_api_key / delete_api_key tools	—	—	✅
App creation POST /api/v1/apps	—	—	— (session-only; API keys not allowed)
App get/delete, key issue/delete/list, stats GET/POST/DELETE /api/v1/apps* (except creation)	—	—	✅ (or session)

Note

App creation (POST /api/v1/apps) is exclusive to dashboard session authentication and cannot be performed with an API key (even a full-scope key returns 401 INVALID_SESSION). All other app operations (get, delete, key issue, key delete, list, stats) can be performed with either dashboard session authentication or a full-scope API key.

Key Lifecycle

• Plaintext shown only at issuance: The plaintext key is included only in the response right after creation. There is no way to retrieve the plaintext afterward; the server stores only a value hashed with HMAC-SHA256 + pepper, and compares hashes against each other during authentication.
• last_used_at updates: Updated every time authentication succeeds. It is not shown in the dashboard UI, but you can check it with the CLI todoke keys list.
• Immediate revocation on deletion: Deleting a key invalidates it immediately. Any application using that key will receive authentication errors (INVALID_API_KEY). Deleted keys cannot be restored.

Rate Limiting

Endpoints that use API key authentication have a rate limit of 20 requests / 60 seconds per IP address. Only failed authentication requests are counted; successful requests with a valid key are not counted. When exceeded, a 429 RATE_LIMITED is returned with a Retry-After: 60 header. For details, see Error Codes & Limits.

Issuing Methods

API keys can be issued in the following three ways.

• Dashboard (the steps at the top of this page)
• CLI: todoke keys add
• MCP: the create_api_key tool (MCP Server. Calling it requires a full-scope key.)