Skip to main content
POST/vault/secrets/{path}

Create Secret

Creates a secret at path from a base64 value, with a visibility and optional metadata.

The creator owns it.

The op query parameter selects another write on an existing secret instead: move gives it a new path, rotate re-seals its current value as a new version, and reveal-challenge returns a single-use challenge for Reveal Secret.

Only the owner can move or rotate a secret.

Parameters
projectId *query

The project's id.

path *path

The secret's path: /-delimited segments, such as database/prod/password.

Request body
One of: object
metadataobject

Optional per-secret tags.

value *string

The secret's value, base64.

Kibo encrypts it before it is stored.

Example: "czNjcjN0LXBhc3N3MHJk"
visibilityany

Who else can list and reveal a secret: private (the owner only, the default) or shared with the listed principals or roles.

One of: object
kind *"private"
or: object
kind *"shared"
principalsstring[]

Subject ids granted read access (usr_/svc_/ext_<base62>).

rolesstring[]

Roles granted read access (e.g. ["PROJECT_ADMIN"] for a project-shared secret).

or: object
newPath *string

The new /-delimited path.

Example: "database/staging/password"
Responses
HTTPK9O CodeDescription
200`op=move`: the secret at its new path. `op=rotate`: its new version. `op=reveal-challenge`: the challenge.
201The secret was created.
400The path or the body isn't valid.
401The request carries no authenticated caller.
403The caller can see the secret but doesn't own it.
404No such secret visible to the caller.
409`K9O_SECRET_ALREADY_EXISTS`: a secret already exists at the path (a create, or a move's new path). `K9O_REKEY_IN_PROGRESS` or `K9O_CUSTODY_TRANSITION_IN_PROGRESS`: a key rotation or custody change is running, so a create or rotate waits. Retry when it completes.
Response body (200)
One of: object
event *string

The ledger event recorded for the move.

Example: "SECRET_PATH_CHANGED"
id *string

sec_<base62>, unchanged by the move.

Example: "sec_4fK9xQ2mZ7"
name *string

The new path-name.

Example: "database/staging/password"
or: object
id *string

sec_<base62>.

Example: "sec_4fK9xQ2mZ7"
ledgerSequenceNumber *integer <int64>

The SECRET_KEY_ROTATED entry's place in the project's signed ledger.

Example: 1842
name *string

The secret's path.

Example: "database/prod/password"
rotatedAt *string <date-time>

When the rotation was sealed.

Example: "2026-11-15T09:30:00.123Z"
version *integer <int64>

The new version, one above the previous.

Example: 4
or: object
challenge *string

rvc_<base62> single-use challenge token.

Example: "rvc_9TqLm2Xa7Pz4"
expiresAt *string <date-time>

Expiry (default +60s).

Example: "2026-11-15T09:31:00.123Z"
Response body (201)
createdAt *string <date-time>

Creation timestamp.

Example: "2026-11-01T08:00:00.000Z"
createdBy *string

Creating principal.

Example: "usr_7Hq2LmN9pR4s"
id *string

sec_<base62>.

Example: "sec_4fK9xQ2mZ7aB"
kid *string

KEK reference.

Example: "vkey_7Rt2Wq9LxP4m"
metadata *object

Per-secret tags.

name *string

The secret's path.

Example: "database/prod/password"
ownerId *string

The secret's owner.

It never changes.

Example: "usr_7Hq2LmN9pR4s"
retiredAtstring <date-time> | null

Retirement timestamp (or null).

Example: "2026-11-15T09:30:00.123Z"
rotatedAtstring <date-time> | null

Last rotation timestamp (or null).

Example: "2026-11-15T09:30:00.123Z"
updatedAt *string <date-time>

Last-update timestamp.

Example: "2026-11-15T09:30:00.123Z"
updatedBy *string

Last-update principal.

Example: "usr_7Hq2LmN9pR4s"
version *integer <int64>

Monotone version.

Example: 3
visibility *any

Who else can list and reveal a secret: private (the owner only, the default) or shared with the listed principals or roles.

One of: object
kind *"private"
or: object
kind *"shared"
principalsstring[]

Subject ids granted read access (usr_/svc_/ext_<base62>).

rolesstring[]

Roles granted read access (e.g. ["PROJECT_ADMIN"] for a project-shared secret).

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.kibo.vault.secrets.create({
  name: '<name>',
  value: 's3cr3t-passw0rd',
  visibility: { kind: 'private' },
  metadata: { team: 'payments' }
})

Showing example in TypeScript

Request example
{
  "value": "czNjcjN0LXBhc3N3MHJk",
  "visibility": {
    "kind": "private"
  },
  "metadata": {
    "team": "payments"
  }
}
Response example (200)
{
  "event": "SECRET_PATH_CHANGED",
  "id": "sec_4fK9xQ2mZ7",
  "name": "database/staging/password"
}
Response example (201)
{
  "createdAt": "2026-11-01T08:00:00.000Z",
  "createdBy": "usr_7Hq2LmN9pR4s",
  "id": "sec_4fK9xQ2mZ7aB",
  "kid": "vkey_7Rt2Wq9LxP4m",
  "metadata": {
    "team": "payments"
  },
  "name": "database/prod/password",
  "ownerId": "usr_7Hq2LmN9pR4s",
  "retiredAt": "2026-11-15T09:30:00.123Z",
  "rotatedAt": "2026-11-15T09:30:00.123Z",
  "updatedAt": "2026-11-15T09:30:00.123Z",
  "updatedBy": "usr_7Hq2LmN9pR4s",
  "version": 3,
  "visibility": {
    "kind": "private"
  }
}

More in Secrets