Get Capsule

GET

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

curl --request GET \
  --url https://example.com/vault/alpha/workspaces/example/engines/example/capsules/example

Returns a capsule’s metadata by ID. Never the payload.

Parameters

Path Parameters

workspace

required

string

The workspace the capsule belongs to.

engine

required

string

Vault engine selector.

id

required

string

The capsule’s identifier.

Responses

200

OK

Media type application/json

Capsule resource: a single-use delivery of a small secret payload to a recipient who holds a link.

The payload is never a field of this message. It is returned exactly once, by RedeemCapsule, to the caller who presents the authorising half of the split token; every other read returns metadata only.

object

id

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

Example

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

default

Default error response

Media type 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"
    }
  ]
}