API Key Authentication & Permission Scopes

All Wisprs API requests authenticate with a bearer token. Keys are scoped — each key only carries the permissions you explicitly grant it, so you can limit exposure in production environments.

Creating a key

Go to Dashboard → API Settings. Name your key, choose an optional expiry, and select scopes. The raw key is shown once on creation — store it securely.

API Settings page showing the Create API Key form with key name, expiry, and scope checkboxes — Dashboard → Settings → API — create and manage keys here

Using your key

Pass the key as a Bearer token in every request:

import { WisprsClient } from '@wisprs/sdk';

const client = new WisprsClient({
  apiKey: process.env.WISPRS_API_KEY!,
});

Scopes

Scope	What it grants
media:ingest	Submit URLs and upload files for transcription
transcriptions:write	Create transcription jobs
transcriptions:read	Read job status and transcript text
exports:read	Download exports (txt, srt, vtt, json, md, docx)
repurpose:run	Generate summaries, chapters, quotes, blog posts, threads
library:search	Semantic search across your transcript library
webhooks:manage	Create and manage webhook endpoints
usage:read	Read your usage metrics and request logs
keys:manage	Create and revoke API keys (restrict carefully)

Rate limits

Rate limits apply per key, per minute:

Tier	Requests / min
Free	10 req/min
Basic	60 req/min
Pro	200 req/min
Enterprise	1,000 req/min

When you hit the limit you receive 429 Too Many Requests with a Retry-After header.

Error responses

json

{
  "success": false,
  "error": "Invalid API key"
}

401 = missing/invalid key · 403 = missing scope · 429 = rate limit exceeded.

FAQ

Can I use OAuth instead of API keys?

Not currently. The API uses bearer token authentication only. OAuth support is on the roadmap for team-level access delegation.

How do I rotate a compromised key?

Go to Dashboard → API Settings, revoke the old key, and create a new one with the same scopes. Old keys are invalidated immediately on revocation.

What happens if I exceed my rate limit?

You receive a 429 Too Many Requests response with a Retry-After header indicating when you can retry. No requests are dropped silently.