Create Capsule

POST

/vault/alpha/workspaces/{workspace}/engines/{engine}/capsules

const url = 'https://example.com/vault/alpha/workspaces/example/engines/example/capsules';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"payload":"example","secret_version":{"secret_id":"example","version_number":"example"},"content_type":"example","ttl":"example","location_id":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/vault/alpha/workspaces/example/engines/example/capsules \
  --header 'Content-Type: application/json' \
  --data '{ "payload": "example", "secret_version": { "secret_id": "example", "version_number": "example" }, "content_type": "example", "ttl": "example", "location_id": "example" }'

Seals a payload into a new capsule and returns its identifier together with the authorising half of the split token — the only time that half is ever returned. The payload is either supplied inline or snapshotted from a stored secret version at this moment; a later rotation of that secret does not change what the capsule delivers.

Parameters

Path Parameters

workspace

required

string

The workspace the capsule is created in.

engine

required

string

Vault engine selector. A create is a point mutation, so the wildcard - is refused with INVALID_ARGUMENT: a write must name exactly one engine.

Request Body^required

application/json

Capsule Input

The client-supplied half of a capsule: what to deliver, and for how long. Separate from the Capsule resource because a create genuinely takes different fields from what a read returns — every field a client may set is set here, and the rest are server-assigned.

object

payload

The payload itself, at most 1 MiB — the bound AddSecretVersion and EncryptWithCryptoKey already carry. A capsule is a credential delivery, not a file transfer; a file belongs behind a presigned URL, and a capsule can carry that URL.

string format: bytes

secret_version

A stored secret version, whose bytes are read at creation and sealed in.

object

secret_id

required

The secret the version belongs to (UUID).

string

version_number

required

The version number to snapshot.

string

content_type

Optional IANA media type of the payload, so the recipient has something to render it by. Defaults to application/octet-stream when omitted.

string

ttl

required

How long the delivery stays collectable, from 1 second to 24 hours.

string

/^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$/

location_id

Weak reference to a topology Location. Defaults to the global location when omitted; immutable after creation.

string

Example ^generated

{
  "payload": "example",
  "secret_version": {
    "secret_id": "example",
    "version_number": "example"
  },
  "content_type": "example",
  "ttl": "example",
  "location_id": "example"
}

Responses

200

application/json

Create Capsule Response

The created capsule, together with the authorising half of its split token — the only response that ever carries that half.

object

capsule

The created capsule’s metadata.

object

The unique identifier of the capsule (UUID).

This is also the PUBLIC half of the split token: it is opaque and server-assigned, so it is safe in an access log and is the only half the anonymous lookup needs.

stringOutput only

workspace_id

The workspace the capsule was created in (UUID, weak reference to taxonomy).

Present on the sender’s view only. The recipient is not entitled to know which tenant sent the delivery, so the anonymous lookup returns a different message entirely rather than a redacted copy of this one.

stringOutput only

engine

The vault engine holding the payload.

string format: enum Output only

Allowed values: VAULT_ENGINE_UNSPECIFIED VAULT_ENGINE_QIBDO VAULT_ENGINE_AWS VAULT_ENGINE_GCP VAULT_ENGINE_AZURE

location_id

Weak reference to a topology Location where the capsule resides. Defaults to the global location when omitted; immutable after creation.

string

name

A short, sayable handle for this capsule, e.g. swift-otter-3f9a21c4.

Server-generated and never client-supplied. A capsule is the one resource whose identifier is also a security boundary, so a sender-chosen handle would be a second way to name the same delivery — and the obvious choices are exactly the strings that must not become guessable.

The SENDER’s handle. The recipient never sees it: a label for a delivery is the sender’s business, and is the kind of context that should not reach whoever holds a guessed identifier.

stringOutput only

state

The capsule’s current state.

string format: enum Output only

Allowed values: CAPSULE_STATE_UNSPECIFIED CAPSULE_STATE_ACTIVE CAPSULE_STATE_REDEEMED CAPSULE_STATE_EXPIRED CAPSULE_STATE_REVOKED

content_type

Optional IANA media type of the payload, so the recipient has something to render it by. Defaults to application/octet-stream when omitted.

string

payload_size_bytes

Size of the payload in bytes.

stringOutput only

expire_time

The deadline. After this instant the capsule is swept to EXPIRED and the payload destroyed, whether or not anyone collected it.

string format: date-time Output only

source_secret_version_id

The secret version the payload was snapshotted FROM at creation, when the capsule was created from a stored secret rather than from inline bytes.

Audit only. It is never resolved again at redemption — rotating the source secret afterwards does not change what this capsule delivers.

stringOutput only

end_time

When the capsule reached a terminal state. Absent while it is active.

string format: date-time Output only

create_time

Creation timestamp (server-managed).

string format: date-time Output only

update_time

Last modification timestamp (server-managed).

string format: date-time Output only

redemption_secret

The AUTHORISING half of the split token, returned exactly once and never again. The platform stores only its digest, so a reader of the database cannot redeem — and neither can the platform re-issue this value.

The sender is responsible for conveying it to the recipient. The platform composes no link and sends no message.

stringOutput only

Example

{
  "capsule": {
    "engine": "VAULT_ENGINE_UNSPECIFIED",
    "state": "CAPSULE_STATE_UNSPECIFIED"
  }
}

default

Default error response

application/json

The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.

object

code

The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].

integer format: int32

message

A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.

string

details

A list of messages that carry the error details. There is a common set of message types for APIs to use.

Array<object>

Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.

object

@type

The type of the serialized message.

string

key

additional properties

any

Example ^generated

{
  "code": 1,
  "message": "example",
  "details": [
    {
      "@type": "example"
    }
  ]
}

Create Capsule

Parameters

Path Parameters

Request Body required

Example generated

Responses

200

Example

default

Example generated

Request Body^required

Example ^generated

Example ^generated