Keys and scopes
Lifecycle
Section titled “Lifecycle”The account owner manages keys in the Mini App (Profile → API keys); keys cannot create or revoke other keys.
- Create. A name, a set of scopes, an optional expiry and an optional credit quota. The
npk_…secret is shown once and never stored — it cannot be viewed again. - Use. Only as
Authorization: Bearer npk_…and only on/api/v1/*paths. No endpoint accepts a user ID: the owner is the key’s owner. - Revoke. Immediate and final; the key’s operation history is kept.
- Limit. At most 20 unrevoked keys per owner (
409 API_KEY_LIMIT_REACHED).
An expired key cannot authenticate new public API requests (401 API_KEY_EXPIRED), including a new
create or Continue command. An already accepted asynchronous task continues under its original key
identity and quota; expiry alone neither cancels the task nor releases its holds. Revoking the key
blocks new paid actions even for an accepted task.
Scopes
Section titled “Scopes”| Scope | Grants |
|---|---|
podcasts:quote |
GET /api/v1/podcasts/voices, POST /api/v1/podcasts/quotes, POST …/:id/continuation-quote |
podcasts:create |
POST /api/v1/podcasts, POST …/:id/cancel, POST …/:id/continue |
podcasts:read |
GET /api/v1/podcasts/:id, …/receipt, …/audio |
news:quote |
GET /api/v1/news/voices, POST /api/v1/news/quotes |
news:create |
POST /api/v1/news, POST /api/v1/news/:taskId/cancel |
news:read |
GET /api/v1/news/:taskId, …/result, …/receipt, …/audio |
tts:quote |
GET /api/v1/tts/voices, POST /api/v1/tts/quotes, POST /api/v1/tts/podcasts/:id/continuation-quote |
tts:create |
POST /api/v1/tts/podcasts, POST …/:id/cancel, POST …/:id/continue |
tts:read |
GET /api/v1/tts/podcasts/:id, …/receipt, …/audio |
The *:create scopes spend credits and are granted only when the owner selects them. No scope grants
publishing, likes, favorites, feed, Source Library, schedule or Hot News authority. A request without
the needed scope gets 403 API_KEY_SCOPE_DENIED.
Key quota
Section titled “Key quota”An optional quota caps the credits a key can hold and spend. A new Podcast or News episode checks it before each
paid request: confirmed cost consumes quota, while unused short holds are released. Historical
Podcast and News receipts retain their original quota accounting; tasks with unsupported saved plans
cannot resume. If quota is insufficient, the episode reports API_KEY_QUOTA_EXCEEDED separately
from low balance; topping up the balance
alone does not raise a key’s quota.