API keys & webhooks
The Developer area holds the credentials and callbacks that let external systems talk to your organization: API keys for the /api/v1 REST API and webhooks that push signed events to your endpoints. Managing either one requires an organization owner or admin role.
API keys
API keys grant programmatic access to the organization's /api/v1 REST API. Each key is scoped to the organization that owns it.
cs_live_prefix — the full token has the formcs_live_<secret>. The server stores only a SHA-256 hash and a short 12-character prefix; a database leak never returns a working key.- Shown only once — the plaintext token exists only at creation time and cannot be recovered afterward. Copy it right away.
- Optional expiration — a key can have an
expiresAtor never expire; an expired key authenticates as invalid. - Revocation (soft) — revoking marks the key as revoked but keeps the row for auditing; a revoked key stops authenticating immediately.
- Last used — each successful authentication stamps
lastUsedAt, useful for spotting idle keys.
The API uses the token as a Bearer; it resolves the organization that owns the key and operates within it. Older keys with the ff_live_ prefix, generated before the rebrand, remain valid because what matters is the hash.
Keys are managed at /dashboard/settings/developer/api-keys.
Webhooks
Webhooks deliver signed events to your HTTPS endpoints, with a delivery history (the ‘calls’). Endpoints are managed at /dashboard/settings/developer/webhooks.
Available events
| Event | Trigger |
|---|---|
enrollment.created | A new enrollment is created |
content.completed | A learner completes the content |
purchase.created | A purchase is recorded |
purchase.refunded | A purchase is refunded |
enrollment.requested | A learner requests enrollment, or a pay-first checkout creates a pending request |
enrollment.approved | A pending enrollment request is approved |
enrollment.rejected | A pending enrollment request is rejected (a pay-first buyer is refunded) |
learner.unenrolled | A learner is removed from a content |
content.published | A content is published |
review.created | A learner posts or updates a review |
community.joined | A learner joins or is assigned to a community |
discussion.post.created | A member posts a question or reply in a community |
How delivery works
- Signing secret — each webhook receives a
whsec_…secret, generated on the server and shown only once at creation. - HMAC signature — the body is sent via
POSTas JSON with the headersx-cursiva-event(the event name) andx-cursiva-signature(HMAC-SHA256 of the body with the secret). Validate the signature on your receiver before trusting the payload. - Timeout and resilience — each delivery has a 5-second time limit; a failed delivery never interrupts the action that triggered it.
- Delivery history — each attempt records the response status, body (truncated), error, success, and duration, queryable as the endpoint’s history of ‘calls’.
- Manual test (ping) — you can send a test event (
webhook.test) to an endpoint and see the attempt in the history. - Enable/disable and delete — inactive endpoints don’t receive the fan-out; only those that are active and subscribed to the event are triggered.
A webhook can be assigned to a team within the organization, via teamId, to group endpoints by owner (personal member or team) in the listing.
REST API
The /api/v1 API manages almost everything the dashboard does. The exact request and response schemas are generated from the same contracts that run the API — see the interactive API reference (in production on its own host, docs.cursiva.io/api). This section is the map: how the API behaves and which resources it covers.
Conventions
Every call shares the same rules:
- Authentication —
Authorization: Bearer cs_live_…. A key resolves to one organization and acts with org-admin authority scoped to it; reaching another organization's data is impossible. - Rate limits — 240 reads/min and 60 writes/min per key. Every response carries
X-RateLimit-Limit,-Remaining, and-Reset; a429addsRetry-After. - Pagination — list endpoints take
pageandpageSize(capped). A page past the end returns an empty array, so you can looppage++until it's empty. - Money — amounts are integer minor units (e.g. cents) paired with a
currency. Amounts in different currencies are never summed into one number. - Errors —
400validation,401bad key,403not permitted,404not found (a resource in another org reads as not-found),429rate-limited. The body is{ "error": "…" }. - Request bodies are JSON, capped at 4 MB.
What you can manage
| Resource | Endpoints (prefix /api/v1) | What you can do |
|---|---|---|
| Organization | GET,PATCH /organization · GET /members · GET /organization/integrations | Read/update the org profile (name, bio, logo), list staff with their roles, check payment/video connection status |
| Custom domain | GET,PUT,DELETE /organization/custom-domain · POST …/verify | Connect a domain, fetch the DNS records, run the ownership check, disconnect |
| Contents | GET,POST /contents · GET,PATCH,DELETE /contents/{id} · POST /contents/{id}/publish · POST /contents/{id}/duplicate | List (paginated + filters), create, edit pricing/theme/access/format/ownership, publish, duplicate the packaging |
| Document | GET,PUT /contents/{id}/document | Read the draft (and published) course document, or replace the draft — headless authoring |
| Learners | GET /learners · GET,POST /contents/{id}/learners · DELETE,POST /contents/{id}/learners/{userId} (reset) | List/search learners, enroll by email (optionally into a cohort), unenroll, reset progress |
| Enrollment requests | GET /contents/{id}/enrollment-requests · POST /enrollment-requests/{id}/approve · …/reject | Read the approval queue with intake answers, approve, or reject (a rejected pay-first buyer is refunded automatically) |
| Communities | GET,POST /contents/{id}/communities · PATCH,DELETE /communities/{id} · members sub-routes | Create/manage cohorts (dates, seats, tutor), add/move/remove members, set the star badge |
| Intake forms | GET,POST /intake-forms · GET,PATCH,DELETE /intake-forms/{id} | Manage reusable enrollment-question sets |
| Tags | GET,POST /tags · PATCH,DELETE /tags/{id} | The org tag registry |
| Coupons | GET,POST /contents/{id}/coupons · PATCH,DELETE /coupons/{id} | Per-content discount codes |
| Teams | GET,POST /teams · GET,PATCH,DELETE /teams/{id} · members sub-routes | Teams and their memberships |
| Sales & purchases | GET /sales · GET /purchases · GET /purchases/{id} · GET /contents/{id}/purchases · POST /purchases/{id}/refund | The order ledger (filter by content, buyer, status, date) and refunds |
| Insights | GET /insights · GET /insights/series · GET /contents/{id}/insights · …/sales | Headline numbers, time series, and per-content academic + sales figures |
| Reviews | GET /contents/{id}/reviews | Read ratings and the review feed (read-only) |
| Webhooks | GET,POST /webhooks · PATCH,DELETE /webhooks/{id} · …/deliveries · …/test | Register and manage the endpoints described above, inspect the delivery log, send a test |
MCP server
Cursiva ships an MCP server (Model Context Protocol) so AI clients — claude.ai, Claude Code, and any MCP-compatible agent — can operate your organization directly. The endpoint is https://mcp.cursiva.io. To connect from Claude Code with a browser login:
claude mcp add --transport http cursiva https://mcp.cursiva.io
Two auth modes are available: OAuth (the server acts as the signed-in user, with their real team roles — editor, finance, community) or an org API key (cs_live_… from Settings → Developer → API keys, org-admin authority, headless). The full guide — all 68 tools, connection steps per client, authoring workflow, and protocol details — lives at MCP server.
Best practices
- Record who created each key or endpoint, which environment it uses, and how to revoke the credential.
- Treat every key and every webhook secret as sensitive: shown once, stored as a hash/cipher, never in the frontend or screenshots.
- Test in the appropriate environment whenever you rotate a key or point a webhook at a new endpoint.