REST API v1

Updated September 27, 2026

The public programmatic API for machine access to secrets. Base URL https://secrets.kryptic.dev (or your self-hosted Secrets API host). The complete OpenAPI document is served at /openapi/v1.json.

The API is end-to-end encrypted: reads return ciphertext envelopes plus the org key sealed to the machine, and writes accept envelopes the caller encrypted locally. The server stores and delivers ciphertext it cannot open. For shell use, prefer kryptic ci export, which performs the decryption chain for you with Kryptic.Encryption.Go. Do not expect a plaintext /export endpoint. The dashboard, the daemon, CI and this API all speak envelopes.

Authentication

Create a machine identity in the dashboard (Machine identities -> New identity). You get a clientId and a one-time clientSecret. Exchange them for a short-lived bearer token:

curl -X POST https://secrets.kryptic.dev/v1/token \
  -H 'Content-Type: application/json' \
  -d '{ "clientId": "kmi_...", "clientSecret": "..." }'

{ "accessToken": "eyJ...", "expiresInSeconds": 900 }

Machine identities can be scoped to specific projects; an unscoped identity sees every project in the organization. Every read and write is audit-logged.

Projects

GET /v1/projects                          # projects the token can access
GET /v1/projects/{publicId}/environments  # environments of one project

Machine key material

Before you can decrypt a bundle, fetch the machine's wrapped private key record:

GET /v1/keys/me
Authorization: Bearer <token>

The response contains the machine's public key, wrapped private key, and Argon2id KDF salt. Derive an unwrap key from the client secret, open the private key, then open the wrappedOrgKey that arrives with each secrets response.

Secrets

Read the ciphertext bundle for one environment. An Org reference in that project is resolved at read time: the bundle includes the catalog envelope and the catalog definition and environment ids, so associated data matches Envelopes. PUT cannot write a Reference or Org reference key. Change the type in the dashboard first, or update the target catalog value.

GET /v1/projects/proj_x/secrets?environment=production
Authorization: Bearer <token>

{
  "projectPublicId": "proj_x",
  "environment": "production",
  "orgKeyId": "key_org_...",
  "wrappedOrgKey": "sbx.v1....",
  "secrets": [
    {
      "key": "DATABASE_URL",
      "envelope": "v1.key_org_....",
      "definitionId": "00000000-0000-0000-0000-000000000001",
      "environmentId": "00000000-0000-0000-0000-000000000002"
    }
  ]
}

Set (create or version) one secret by uploading an envelope you encrypted under the org key in your own process:

PUT /v1/projects/proj_x/secrets/DATABASE_URL
Authorization: Bearer <token>
Content-Type: application/json

{ "environment": "production", "envelope": "v1.key_org_...." }

Delete a secret definition across all environments:

DELETE /v1/projects/proj_x/secrets/DATABASE_URL
Authorization: Bearer <token>

Dynamic secrets

Enterprise leases use the same machine token:

POST /v1/dynamic-secrets/leases?projectPublicId=proj_x&environment=production&key=APP_DB
GET  /v1/dynamic-secrets/leases/{leaseId}
GET  /v1/dynamic-secrets/leases/{leaseId}/envelope
POST /v1/dynamic-secrets/connectors
GET  /v1/dynamic-secrets/work
POST /v1/dynamic-secrets/work/complete

Work items include the provider-config envelope and the machine's wrapped org key. Minting happens on kryptic connector run, not on this host. See Dynamic secrets.

Errors