Cybernethicc Vault API

Authentication

Two auth mechanisms, depending on the endpoint.

Bearer service token

Service tokens are scoped to a single Secret Project + optional environment list. They carry the key material needed to decrypt that project's secrets server-side, so the holder never needs the master password. Used by CI runners, scripts, and tunnel clients.

Authorization: Bearer cyb_<token_id_prefix>_<key_fragment>

Mint a service token from portal.cybernethicc.com/vault → project → Service tokens. The plaintext is shown once at creation; rotate by issuing a new one and revoking the old.

Short-lived URL token

Secret Send links carry a URL-safe token in the path. No header needed. The token is consumed on first successful read for burn-on-read secrets.

GET /api/v1/public/vault/secrets/<url_token>

Endpoint reference

Public, programmatic Vault endpoints. JWT-only routes (item CRUD, vault unlock, passkey, TOTP) are not listed, those are driven by the portal UI.

Fetch secrets with a service token

The common CI pattern: store credentials in a Vault Secret Project, issue a service token scoped to that project + environment, and read values from a script.

Query parameters

Request

curl -fsS "https://portal.cybernethicc.com/api/v1/public/vault/secrets?env=prod&decrypt=server" \
  -H "Authorization: Bearer cyb_6fc0b1c2789ed180_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"

Response (200 OK)

{
  "project_slug": "billing-api",
  "env_slug": "prod",
  "values": {
    "DB_PASSWORD": "s3cret-prod-pw",
    "STRIPE_API_KEY": "sk_live_..."
  }
}

Error responses

401 { "error": { "code": "UNAUTHORIZED", "message": "Token revoked or unknown" } }
401 { "error": { "code": "UNAUTHORIZED", "message": "Missing Authorization header" } }
403 { "error": { "code": "FORBIDDEN",    "message": "Token has no access to the requested env(s)" } }

Consume a Secret Send

Receive-side endpoint for the public Secret Send link. Returns the encrypted blob plus metadata; decrypt locally using the password / key fragment shipped out-of-band.

Request

curl -fsS https://portal.cybernethicc.com/api/v1/public/vault/secrets/abc123def456

Response (200 OK)

{
  "data": {
    "ciphertext_b64": "GpKx...",
    "iv_b64":         "qY1n...",
    "tag_b64":        "lZmd...",
    "burn_on_read":   true,
    "views_remaining": 0,
    "has_password":   false
  }
}

Each successful read counts as a view. Once the last view is used (immediately for a burn-on-read secret) the link stops working and later requests return 404. A password-protected secret answers the GET with {"data":{"password_required":true}}; send the password with POST to the same URL as {"password":"..."}. A wrong password returns 403, and too many wrong attempts lock the link for an hour (429).

Error responses

404 { "error": { "code": "NOT_FOUND", "message": "Secret not found or already viewed" } }
403 { "error": { "code": "FORBIDDEN", "message": "Wrong password." } }
429 { "error": { "code": "TOO_MANY_REQUESTS", "message": "Too many wrong passwords. Try again in an hour." } }

Service tokens

Service tokens have three pieces of state inside them, packed into a single bearer string:

• The token id prefix: points the server at the right hashed token row.
• A 32-byte key fragment, wraps the project encryption key (PEK), so server-side decryption is possible without the master password.
• The scope: project id + optional environment whitelist, stored server-side.

Token format:

cyb_<token_id_prefix>_<base64url_key_fragment>

Lifecycle

• Create: issue in portal → vault project → service tokens. Plaintext is shown once; the server keeps only a hash.
• Use: pass as Authorization: Bearer. Every use writes an audit row with IP + user agent.
• Revoke: mark inactive in the portal. The next request fails 401 UNAUTHORIZED.
• Rotate: issue a new token, deploy it to your CI, then revoke the old one.

Errors

All error responses share the same shape:

{
  "error": {
    "code":    "FORBIDDEN",
    "message": "Token has no access to the requested env(s)"
  }
}