REST API
The API is a Cloudflare Worker. All application endpoints are under /v1 and require
authentication. Values are always ciphertext — the API neither encrypts nor decrypts.
Authentication
Send one of:
Authorization: Bearer <jwt>— a Stytch B2B session JWT (web sessions).Authorization: Bearer skt_…— a service token.x-seekrit-dev-user: <email>— local dev only, when the worker runs withAUTH_MODE=dev.
Errors use { "error": { "code": "...", "message": "..." } } with a matching HTTP status
(400, 401, 403, 404, 409, 500). Organizations you don't belong to return 404.
Health
| Method | Path | Description |
|---|---|---|
GET | /health | Liveness check (no auth). |
Identity
| Method | Path | Description |
|---|---|---|
GET | /v1/me | The current user and their organizations. |
GET | /v1/me/keys | Your public key and passphrase-encrypted private key. |
PUT | /v1/me/keys | Upload your keys (one-time key setup). |
Organizations
| Method | Path | Description |
|---|---|---|
GET | /v1/orgs | List organizations you can access. |
POST | /v1/orgs | Create an organization (creator becomes owner). |
GET | /v1/orgs/:orgId | Get one organization and your role. |
GET | /v1/orgs/:orgId/members | List members (includes public keys, for granting). |
Applications & environments
| Method | Path | Description |
|---|---|---|
GET | /v1/orgs/:orgId/apps | List applications. |
POST | /v1/orgs/:orgId/apps | Create an application. (admin) |
GET | /v1/orgs/:orgId/apps/:appId | Get an application and its environments. |
DELETE | /v1/orgs/:orgId/apps/:appId | Delete an application. (admin) |
GET | /v1/orgs/:orgId/apps/:appId/envs | List environments. |
POST | /v1/orgs/:orgId/apps/:appId/envs | Create an environment (body includes the wrapped DEK). (admin) |
GET | /v1/orgs/:orgId/envs/:envId | Get an environment. |
DELETE | /v1/orgs/:orgId/envs/:envId | Delete an environment. (admin) |
Secrets
Values are opaque ciphertext blobs produced by the client.
| Method | Path | Description |
|---|---|---|
GET | /v1/orgs/:orgId/envs/:envId/secrets | List secrets (with ciphertext). |
PUT | /v1/orgs/:orgId/envs/:envId/secrets/:name | Create or update a secret (appends a version). |
DELETE | /v1/orgs/:orgId/envs/:envId/secrets/:name | Delete a secret. |
Key grants
| Method | Path | Description |
|---|---|---|
GET | /v1/orgs/:orgId/envs/:envId/key | The calling principal's own wrapped DEK. |
GET | /v1/orgs/:orgId/envs/:envId/keys | List all grants for the environment. (admin) |
POST | /v1/orgs/:orgId/envs/:envId/keys | Grant a wrapped DEK to a principal. (admin) |
DELETE | /v1/orgs/:orgId/envs/:envId/keys/:grantId | Revoke a grant. (admin) |
Service tokens
| Method | Path | Description |
|---|---|---|
GET | /v1/orgs/:orgId/tokens | List service tokens. (admin) |
POST | /v1/orgs/:orgId/tokens | Register a token (client sends hash + public key). (admin) |
DELETE | /v1/orgs/:orgId/tokens/:tokenId | Revoke a token. (admin) |
Audit
| Method | Path | Description |
|---|---|---|
GET | /v1/orgs/:orgId/audit | Paginated audit entries. (admin) Query: cursor, limit, action, resourceType. |
note
Token creation is client-driven: the client generates the keypair and token string locally and submits only the token id, a SHA-256 hash, and the public key. The server never sees the token secret.