Concepts

Reference for the core terms, types, and entities in SikkerKey. Sections are organized for lookup; jump to whatever you need. For a top-to-bottom explanation of how the pieces fit together, see Introduction. For a hands-on walkthrough, see Quickstart.

Vault

Your vault is your account's encrypted secrets storage. Each vault has a unique ID (e.g. vault_a1b2c3d4e5f6g7h8) that machines use to identify which vault they belong to. A machine can be registered with multiple vaults, each with its own keypair and identity.

Vaults come in two shapes:

• Personal: a single human owns and acts on the vault. This is what every account starts as.
• Organization: an owner plus a set of invited members. Each member holds a permission template that defines what they can do; every action is attributed to the acting member in the audit log.

The conversion from personal to organization is a one-way operation from Settings. The vault ID, projects, secrets, machines, and machine-authentication keypairs stay exactly the same; the trust shape around the dashboard expands to admit additional human users. See Organizations overview.

Projects

Projects group secrets and machines into logical environments. A project might represent:

• An environment: production, staging, development
• A service: payment-api, auth-service
• A team: backend, infrastructure

Each project has its own independent encryption key. Secrets belong to exactly one project. Machines can be added to multiple projects, but their secret access is still per-secret within each project.

Secret Types

SikkerKey has five secret types.

Secrets

A single encrypted value with a name. API keys, passwords, connection strings, tokens. Read with getSecret(). Optionally enable automatic rotation so SikkerKey generates a new value on a schedule.

Structured Secrets

Multiple named fields encrypted as a single blob (e.g. host, username, password). Individual fields can be read via getFields() or getField() without parsing the full value:

creds = sk.get_fields("sk_db_prod")
host = creds["host"]
password = creds["password"]

Optionally enable automatic rotation on a per-field basis. You choose which fields rotate (e.g. password) and which stay static (e.g. host, username).

Managed Secrets

Database credentials that SikkerKey rotates on a schedule and pushes to your database automatically. Always structured with username and password fields. A CLI agent runs locally next to your database, monitors for rotations, and applies the new password via the appropriate SQL command (e.g. ALTER ROLE for PostgreSQL). The database is never exposed to the internet.

Canary Secrets

Tripwire credentials that machines can be granted access to but are not meant to be read in normal operation. The moment a granted machine fetches one, SikkerKey records a critical audit entry, freezes the surrounding project (no further machine reads succeed in that project until the vault owner unfreezes it), and dispatches every alert configured for the canary action. The machine still receives the decrypted value so the attacker keeps going while the operator investigates. Configurable per canary: which triggers fire (project freeze, related-canary cascading) and where alerts route. See Canary Secrets.

TTL Secrets

One-time self-destructing secrets for sharing credentials with people who don't have access to your vault. You paste or generate a value, set a self-destruct timer (1 minute to 24 hours), and get a link plus a passphrase. The recipient opens the link, enters the passphrase, and sees the secret. It's then permanently destroyed. A wrong passphrase also destroys it immediately. TTL secrets are encrypted with AES-256-GCM at rest, the passphrase is hashed with Argon2id, and machines cannot access them. They exist for human-to-human credential handoff, not programmatic access.

Encryption

SikkerKey uses envelope encryption with three layers:

1. Each secret gets a random AES-256-GCM data key
2. The data key encrypts the secret value, with the secret ID bound as Additional Authenticated Data (AAD)
3. The project's master key encrypts the data key
4. Both encrypted blobs are stored

The AAD binding means an encrypted value cannot be swapped between secrets. Decryption fails if the secret ID doesn't match.

Every change creates a new version. Previous versions are preserved for rollback, subject to your plan's version retention limit.

Automatic Rotation

Any secret or structured secret can optionally have automatic rotation enabled. You configure:

• Interval: how often to rotate (minimum 5 minutes)
• Length: generated value length (default 32)
• Charset: symbols (default), alphanumeric, numbers, or uuid
• Fields (structured secrets only): which fields rotate, others stay static

Secrets with active rotation cannot be manually replaced or rotated. Each rotation creates a new version.

Managed secrets always have rotation enabled.

Soft Delete

Deleted secrets are moved to trash and remain recoverable for 30 days. After 30 days, the secret and all its version history are permanently deleted. Machine access grants and rotation schedules are removed immediately on deletion.

Machines

A machine is any server, container, or process that needs to read secrets. Every machine has an Ed25519 keypair and a unique machine ID. There are three ways a machine receives its identity.

Bootstrap

A long-lived machine such as a server or VM runs the bootstrap command on itself.

1. The machine generates an Ed25519 keypair locally
2. The public key is sent to SikkerKey
3. The private key stays on the machine at ~/.sikkerkey/vaults/{vaultId}/private.pem

The private key is never transmitted. SikkerKey only stores the public key.

Newly bootstrapped machines start as pending. They cannot authenticate until the vault owner approves them from the dashboard.

Pre-Provisioning

For containers where running an interactive bootstrap is impractical, the vault owner provisions a machine identity from the dashboard. SikkerKey generates the keypair server-side, approves the machine, links it to a project, and grants access to the selected secrets. The resulting bundle (identity.json, private.pem, cli.json) is delivered once via a single-use download link and then deleted from SikkerKey.

A pre-provisioned machine uses the same Ed25519 authentication as any other machine. The only difference is how the keypair was generated and delivered. Once the bundle is in the container, the SDK and CLI treat it identically to a bootstrap-created identity.

Ephemeral Machines

For fleets that come and go too quickly to approve by hand, such as CI runners, autoscaling groups, and short-lived containers, SikkerKey issues enrollment tokens. An enrollment token is a reusable policy template that specifies which projects enrolling machines join, which secrets they receive, and how long each machine lives.

Each enrolled machine generates its own Ed25519 keypair locally (same as bootstrap), but is auto-approved and assigned a fixed expiration timestamp. When the timestamp passes, authentication is refused and the machine is auto-disabled. After a 30-day retention period, the row is permanently deleted.

A single token can enroll up to 10,000 machines. Tokens themselves expire after their configured lifetime or when max uses is reached. See Ephemeral Machines for the full lifecycle, restrictions, and audit model.

Temporary Machines

For short, scoped workloads that need a single time-boxed identity (pen-test runs, incident response, migrations, demos, contractor engagements, time-bounded audits), SikkerKey issues temporary machine tokens. A temporary machine token is single-use and produces one machine with a configured lifetime between one hour and twelve months.

Unlike ephemeral machines, the registered machine is pending and requires manual approval. Projects and secrets are granted after approval, the same way they are for bootstrap-registered machines. The token does not pre-bake project membership or secret access.

Temp machines layer three opt-in per-machine guardrails on top of the standard checks: an IP allowlist, a country allowlist resolved from the source IP, and a time-of-day window evaluated against an IANA timezone with selected weekdays. Each axis is enforced on every signed request; a failure on any enabled axis is rejected with HTTP 403 and recorded as temp_machine_blocked.

The expiry can be extended after issuance, capped at a rolling twelve months of remaining lifetime. The most recent un-reverted extension can be reverted in one step. See Temporary Machines for the full lifecycle, guardrail evaluation order, and audit model.

Machines can be disabled at any time, immediately revoking their ability to authenticate.

Machine Authentication

Every request is signed with the machine's Ed25519 private key. The signed payload is method:path:timestamp:nonce:bodyHash. The request carries four headers:

The server verifies:

1. Lockout: 3 failed attempts from the same IP within 5 minutes triggers a 30-minute lockout
2. Machine status: must be approved and enabled
3. Signature: verified against the stored public key
4. Timestamp: must be within 5 minutes of server time
5. Nonce: must not have been used before (tracked in the database, survives restarts)
6. Account status: the vault owner's account must be active

An intercepted request is useless. The timestamp expires, the nonce is consumed, and the signature can't be forged without the private key.

Access Requirements

For a machine to read a single secret, all of the following must be true:

1. Valid Ed25519 signature with a fresh nonce
2. Machine is approved and enabled
3. The project is not frozen (a canary trigger or a manual freeze blocks every read in the project until the vault owner clears it)
4. Machine is added to the project containing the secret
5. Machine has an explicit grant to that specific secret

There is no wildcard access, no "grant all", no inheritance. Each machine-to-secret relationship is explicit.

Access Policies (opt-in)

A secret can also be bound to a project-scoped access policy that adds additional conditions on every read. Without a binding, the five requirements above are the full check. With a binding, each enabled axis on the policy is evaluated and the read is rejected if any axis fails.

Six axes, composable per policy:

• Time window: only readable on configured weekdays inside an HH:mm-HH:mm range in a chosen IANA timezone.
• IP / CIDR allowlist: source IP must match. Per-secret, distinct from the vault-wide IP allowlist.
• Read-rate cap: max reads per minute and/or per UTC day, per bound secret.
• Co-sign: another named machine in the same project must have read this same secret within a configured window before this fetch is allowed.
• TTL: bound secret is destroyed at a fixed time, or after N total reads.
• Rotate after N reads: queues an immediate rotation when the current version's read count crosses a threshold.

Policies are managed from each project's Policies sub-page. Vault owners always have full policy management; organization members need a template that grants the Policies: Manage capability and a project scope that includes the project. See Access Policies for the full evaluation order, HTTP status semantics, and audit entries.

Organizations

An organization vault is a vault that accepts more than one human user. The owner converts their personal vault to an organization, invites people by email, and assigns each member a permission template that defines what they can do. Every action a member takes is attributed to them in the audit log.

Membership joins an existing SikkerKey user identity to the vault. The owner cannot create accounts on a member's behalf; the recipient must already have signed up. Members hold their own credentials and sign in as themselves, then pick which vault to act inside for the session.

Permission templates bundle capabilities (what the member can do) and a project scope (which projects the project-scoped capabilities apply to). The same template can be assigned to many members; changing a template's grants takes effect on every holder's next request. Three capabilities are owner-only — editing templates, assigning a template to a member, and changing a member's project scope — to keep the privilege-escalation surface in one hand.

Suspension is reversible and immediate: a suspended member is cut from the vault on their next request. Removal is permanent for the membership but leaves the member's own SikkerKey account intact.

The conversion from personal to organization is one-way. Machines on the vault keep authenticating with their existing Ed25519 keypairs; organization membership is a dashboard concept and has no effect on the machine plane.

See Organizations overview for the full feature surface.

AI Agents

An AI agent is a management-plane identity for an AI client (Claude Code, Codex, Cursor, Continue). It is a structurally separate identity class from machines: distinct database table, distinct authentication route surface, no path to read the plaintext content of a stored secret.

AI agents authenticate with the same Ed25519 signed-request scheme as machines, but they hit /v1/ai/... routes and the lookup never crosses into the machines table. An AI agent's id is invisible to the machine-auth path; a machine's id is invisible to the AI-auth path.

Scopes

Each AI agent holds a flat set of scope strings granted at provisioning time. Scopes are validated against an allowlist on the server, and each route declares which scope it requires. The vault owner sees the scope set in the dashboard and can edit or revoke it at any time.

Scope-set mutation is dashboard-only. An AI agent cannot grant itself, or another agent, scopes it doesn't already hold. The same restriction applies to the project allowlist below.

Common scopes include machines.read, projects.secrets.write, audit.read, alerts.write. The full set is in the MCP Security Model.

Project Allowlist

In addition to scopes, an AI agent can be configured with an explicit list of project IDs. If non-empty, the agent's project-context scopes (projects.*) are filtered to those projects: operations against any other project return HTTP 403. Empty allowlist means every project the vault owner has, current and future.

When a restricted agent creates a new project, the new project's id is automatically added to its allowlist so the agent can manage what it just made.

Plaintext Boundary

No tool exposed to AI agents returns the plaintext content of a stored secret. Read endpoints return only metadata. Write endpoints (create, update_value, rotate, dynamic_create) accept plaintext as input, encrypt it server-side with the same envelope encryption regular secrets use, and never round-trip the value back.

The one intentional exception is the temporary-secret create primitive, which returns a one-shot share link plus passphrase intended for delivery to a human recipient. Opening the link from the AI surface destroys the secret without delivering it.

Provisioning

AI agents are provisioned from the dashboard's Machines page (AI Agents tab). The flow issues a one-time bootstrap token, which the customer redeems by running sikkerkey-mcp install <token> on the machine that will host the AI client. The MCP binary generates the Ed25519 keypair locally and sends only the public key to SikkerKey. The private key never leaves the host.

Bootstrap-token issuance is dashboard-only by design (an AI agent can't provision new AI agents). See MCP Setup for the end-to-end flow and the supported AI clients.

Audit

Every action through an AI agent is signed and recorded in the audit log with the agent's id and name attached. The dashboard surfaces AI-agent-attributed entries with a distinct badge so they're not mixed up with machine activity. See Audit Logging for the full attribution model.

Audit Log

Every vault action is recorded in an append-only audit log with a severity classification ranging from info to critical. Entries are pushed to the dashboard in real time via server-sent events and optionally emailed or sent to a webhook. See Audit Logging for the full action-to-severity map, retention details, and alert integration.

Audit log retention is based on your subscription plan and is pruned automatically.