Stemma has an early API: scoped ctm_ keys that can be limited to specific vaults, signed webhooks, honest usage numbers, and an OpenAPI reference generated from the server itself. It is deliberately small, and this page tells you exactly where its edges are.
Everything the API exposes respects the same rule as the product: the server holds ciphertext and metadata, never readable records and never keys.
List vaults, create and update items, manage the trash lifecycle. Every item payload is an encrypted envelope sealed on the client: your integration moves records, and only your own client-side keys can open them.
Subscribe an HTTPS endpoint to item and vault events. Each delivery is HMAC-signed with a secret only you were shown, and carries an idempotency key so retries never double-process.
A read-only scope exposes the account audit trail, so compliance tooling can watch the record of actions without ever holding a write credential.
An API key is a narrow instrument, not a second login. You choose its permissions from the server’s catalog, optionally pin it to specific vaults, give it an expiry, and rotate or revoke it from the desk at any time.
Keys are created in Settings → Developer on the Professional plan. Every key starts with the ctm_ prefix, is shown exactly once, and is stored by us only as a hash.
Permissions come from a server-published catalog — read or write on vaults, items, and audit. A key can also be restricted to specific vaults, so a tax integration can see the household binder and nothing else.
Send the key as a Bearer token. Out-of-scope requests fail closed with 403 INSUFFICIENT_SCOPE — a vault-restricted key cannot even list vaults outside its set.
# List the vaults this key is allowed to see
curl https://api.trystemma.com/api/v1/vaults \
-H "Authorization: Bearer $STEMMA_API_KEY"
# A vault-scoped key answering for a vault outside its set:
# 403 { "error": { "code": "INSUFFICIENT_SCOPE", … } }/api/v1/developer/scopesThe permission and webhook-event catalog — the single source of truth this page defers to. Events the server accepts but does not deliver yet are flagged emitted: false.
/api/v1/developer/usageReal request totals with a per-key daily series, counted per authenticated request — not an estimate.
/api/v1/developer/keysCreate a key with explicit permissions, an optional expiry, and an optional vault allow-set.
/api/openapi.jsonThe machine-readable OpenAPI spec, generated from the server’s own route annotations.
Each webhook body is signed with HMAC-SHA256 using the whsec_ secret shown once at creation. The signature arrives in the X-Stemma-Signature header as sha256=<hex>, computed over the raw request body. Compare it timing-safely, and use the Idempotency-Key header to drop redeliveries.
import { createHmac, timingSafeEqual } from 'node:crypto';
// Verify a Stemma webhook delivery.
// secret: the whsec_… value shown once when the webhook was created.
export function verifyStemmaWebhook(rawBody, headers, secret) {
const received = headers['x-stemma-signature'] ?? ''; // "sha256=<hex>"
const expected = 'sha256=' +
createHmac('sha256', secret).update(rawBody).digest('hex');
const a = Buffer.from(received);
const b = Buffer.from(expected);
return a.length === b.length && timingSafeEqual(a, b); // timing-safe
}We publish what the API is today, not what a roadmap hopes it becomes. Four things worth knowing before you build:
Authentication, vaults, items, webhooks, usage, and audit. It will grow, and responses may gain fields — build tolerant parsers.
The scope catalog marks each webhook event with an emitted flag. If it says false, subscribing works but nothing will arrive yet — we would rather tell you than let an integration wait on a ghost.
Keys are personal bearer credentials for your own account. Third-party app authorization and published rate guarantees are future work, not fine print.
The API never returns plaintext vault content and cannot be asked to. Decryption belongs to clients holding the keys — that boundary is the product, and it applies to integrations too.