API reference

Synchronous hush-hush client.

A single instance handles both read and write calls. The credential is only actually required by hush-hush on write operations (create/update/delete); reads (get, used-by, audit-log query) succeed without one, since hush-hush's confidentiality boundary is "who holds a matching private key," not who's calling the endpoint.

Parameters:

Name	Type	Description	Default
base_url	str	Base URL of the hush-hush instance to call, e.g. "https://hush-hush.example.com".	required
api_key	str | None	Bearer credential for write operations. Falls back to the HUSH_HUSH_API_KEY environment variable when not given.	None
timeout	float	Per-request timeout, in seconds.	DEFAULT_TIMEOUT
max_retries	int	How many times a request is retried after a network failure or a 5xx/429 response before the error is raised to the caller. Any other 4xx is never retried.	3

create_object(slug, value, *, used_by=None, caller=None)

Stores an already-sealed value under a new, caller-chosen slug. Requires a credential (see api_key/HUSH_HUSH_API_KEY).

Parameters:

Name	Type	Description	Default
slug	str	The new object's slug. Must match hush-hush's slug pattern (lowercase alphanumeric, -/_).	required
value	bytes	The already-sealed (encrypted) value. This SDK never encrypts or decrypts anything — hush-hush stores whatever bytes it's given as opaque ciphertext.	required
used_by	list[str] | None	Consumers (repos or hosts) recorded as depending on this object. Set once, at creation; unaffected by later value updates.	None
caller	str | None	Recorded in the audit log as the calling program's self-reported identity. Not verified by the server.	None

Returns:

Type	Description
ObjectMetadata	The created object's metadata.

Raises:

Type	Description
APIError	If the server responds with anything other than 201 (for example, 401 for a missing/invalid credential, or 409 if an object already exists under that slug).

delete_object(slug, *, caller=None)

Permanently removes an object. A subsequent get by this slug returns a 404 APIError. Requires a credential.

Parameters:

Name	Type	Description	Default
slug	str	The object's slug.	required
caller	str | None	Recorded in the audit log as the calling program's self-reported identity. Not verified by the server.	None

Raises:

Type	Description
APIError	If the server responds with anything other than 204 (for example, 401 or 404).

get_object(slug, *, caller=None)

Fetches an object's sealed ciphertext exactly as stored — this SDK never decrypts it, the same as the server. Needs no credential.

Parameters:

Name	Type	Description	Default
slug	str	The object's slug.	required
caller	str | None	Recorded in the audit log as the calling program's self-reported identity. Not verified by the server.	None

Returns:

Type	Description
bytes	The object's raw sealed ciphertext.

Raises:

Type	Description
APIError	If the server responds with anything other than 200 (for example, 404 if no object exists under that slug).

get_object_used_by(slug)

Returns the recorded list of consumers for an object — the "what depends on this" mapping set at creation. Needs no credential.

Parameters:

Name	Type	Description	Default
slug	str	The object's slug.	required

Returns:

Type	Description
UsedBy	The object's recorded consumers.

Raises:

Type	Description
APIError	If the server responds with anything other than 200 (for example, 404 if no object exists under that slug).

health()

Checks whether hush-hush is up. Needs no credential.

Returns:

Type	Description
Health	The server's health status.

Raises:

Type	Description
APIError	If the server responds with anything other than 200.

query_audit_log(*, object_id=None, caller=None, from_=None, to=None, order='asc')

Queries the audit log — every create, read, update, and delete call is recorded here. Needs no credential. Filters combine with AND when more than one is given.

hush-hush's /audit-log endpoint has no pagination parameters, so this always returns the full matching result set as a single list, never a page plus a cursor.

Parameters:

Name	Type	Description	Default
object_id	str | None	Restrict to entries for this object id.	None
caller	str | None	Restrict to entries recorded with this caller identity.	None
from_	datetime | None	Restrict to entries at or after this time.	None
to	datetime | None	Restrict to entries at or before this time.	None
order	Literal['asc', 'desc']	"asc" (the default) returns oldest entries first, "desc" newest first. Only "asc" and "desc" are accepted, and a type checker rejects anything else.	'asc'

Returns:

Type	Description
list[AuditLogEntry]	Matching audit log entries, in the requested order.

Raises:

Type	Description
APIError	If the server responds with anything other than 200.

update_object(slug, value, *, caller=None)

Replaces the stored ciphertext for an existing object. The object's slug and used-by metadata are unchanged. Requires a credential.

Parameters:

Name	Type	Description	Default
slug	str	The existing object's slug.	required
value	bytes	The new already-sealed (encrypted) value.	required
caller	str | None	Recorded in the audit log as the calling program's self-reported identity. Not verified by the server.	None

Returns:

Type	Description
ObjectMetadata	The updated object's metadata.

Raises:

Type	Description
APIError	If the server responds with anything other than 200 (for example, 401 or 404).

Asynchronous hush-hush client — see Client for the shared behavior every method here has an await-able equivalent of.

create_object(slug, value, *, used_by=None, caller=None) async

See Client.create_object.

delete_object(slug, *, caller=None) async

See Client.delete_object.

get_object(slug, *, caller=None) async

See Client.get_object.

get_object_used_by(slug) async

See Client.get_object_used_by.

health() async

See Client.health.

query_audit_log(*, object_id=None, caller=None, from_=None, to=None, order='asc') async

See Client.query_audit_log.

update_object(slug, value, *, caller=None) async

See Client.update_object.

Bases: Exception

Raised for any non-2xx response from hush-hush.

Attributes:

Name	Type	Description
status_code		The HTTP status hush-hush responded with.
request_id	str | None	Populated when the response carries a documented request-ID header; hush-hush's spec doesn't currently document one, so this is usually None. Kept as an attribute rather than omitted so a future spec addition doesn't change this type's shape.
message	str | None	The parsed error field from hush-hush's error body, or None if the body wasn't the expected shape.
body	bytes	The raw, unparsed response body, for a caller that needs more than message.

Models

Generated model types returned by Client/AsyncClient's own methods — documented here so a reference to one elsewhere on this site links to a real page instead of rendering as plain text.

Attributes:

Name	Type	Description
status	Literal['ok']
version	str	The running server's own version, as goreleaser stamped it - "dev" for a plain go build. The web UI's footer links this to the changelog page rather than hardcoding a version that would drift from what's actually running.
environment	str | Unset	The operator's own short label for this instance, from the INSTANCE_LABEL setting - for example prod / homelab. The web UI's top bar shows it so an operator can tell instances apart. Omitted when no label is set. This endpoint is unauthenticated, so the label is public: never put anything sensitive in it.

Attributes:

Name	Type	Description
id	UUID	The object's UUID. Several objects can share a name (each is a variant, with its own value and consumers), so this is what tells them apart and what id selects.
slug	str	A caller-chosen, unique identifier for an object - what every documented request path (URL, CLI, API) addresses it by. Letters of either case, digits, _ and -, starting with a letter or digit; names are case-sensitive, so Api_Token and api_token are two secrets. Create and rename follow the same rule. The object's internal id is a separate, opaque value never exposed to or accepted from a caller (specs/secret-objects/spec.md's "Internal id decoupled from user-facing slug" requirement).
tags	list[str]	Labels for grouping and filtering objects (GET /objects?tag=). Free-form, 1 to 32 characters from a-z 0-9 . _ / -, at most 10 per object. Uppercase is converted to lowercase and duplicates are dropped. Metadata only - never part of the sealed value. A response always carries the array, empty when the object has none.
used_by	list[str] | Unset	The consumers (repos or hosts) recorded as depending on this object. Set at creation, and replaceable later via UpdateObjectRequest's own used_by field - a plain value update that omits it leaves the list as it was. A consumer named more than once is recorded once.
description	str | Unset	A free-text label set at creation, for a reader who only knows the slug. Fixed at creation - there is no way to change it later.
keep_readable_copy	bool | Unset	Requests that the owner's own escrowed identity public key be included as an additional decrypt recipient, alongside whatever consumer recipients the client already resolved (specs/secret-objects/spec.md's "Opt-in owner-recipient inclusion at create time" requirement). Omitting this field (the default) means the owner is not added as a recipient - this service never makes ownership imply decrypt access on its own. This is a client-side sealing instruction, not something this service enforces or verifies: it never decrypts, and never adds a recipient to value itself - the caller has to add the owner's public key (GET /auth/identity) to its own recipient list before sealing. A create or update response echoes back exactly what that same request asked for; it isn't persisted, so a later fetch never carries this field.
created_at	datetime | Unset	When the object was created. Returned by GET /objects; left out of a create or update response.
updated_at	datetime | Unset	When the object's value was last replaced - equal to created_at for an object never updated. Returned by GET /objects; left out of a create or update response.
created_by	Actor | Unset	Who performed an audited write. type is session (the admin account, id is its actor id), token (a write token, id is its token id) or consumer_token (a consumer token, id is its id) - the same values GET /audit-log reports.
updated_by	Actor | Unset	Who performed an audited write. type is session (the admin account, id is its actor id), token (a write token, id is its token id) or consumer_token (a consumer token, id is its id) - the same values GET /audit-log reports.

Attributes:

Name	Type	Description
used_by	list[str]	The consumers (repos or hosts) recorded as depending on this object. Set at creation, and replaceable later via UpdateObjectRequest's own used_by field - a plain value update that omits it leaves the list as it was. A consumer named more than once is recorded once.

Attributes:

Name	Type	Description
id	int	This entry's own id - stable and strictly increasing, so it doubles as the cursor for the after query parameter.
object_id	str	A caller-chosen, unique identifier for an object - what every documented request path (URL, CLI, API) addresses it by. Letters of either case, digits, _ and -, starting with a letter or digit; names are case-sensitive, so Api_Token and api_token are two secrets. Create and rename follow the same rule. The object's internal id is a separate, opaque value never exposed to or accepted from a caller (specs/secret-objects/spec.md's "Internal id decoupled from user-facing slug" requirement).
action	AuditLogEntryAction
timestamp	datetime
ip	str	The request's source IP. Unlike caller, this is never self-reported - it's the one piece of the request nobody gets to lie about via a header. Currently the immediate TCP peer's address; this service isn't deployed behind a reverse proxy or load balancer, so X-Forwarded-For (or similar) support isn't implemented yet.
variant_id	UUID | Unset	The UUID of the object the entry is about. object_id is only its name, which several variants can share. Left out of an entry written before this was recorded.
caller	str | Unset	The caller's presented identity, if any.
actor_type	AuditLogEntryActorType | Unset	The kind of verified credential that authenticated this call - absent for an unauthenticated read. Unlike caller, this is never self-reported.
actor_id	str | Unset	The specific token id or admin account this call was authenticated as - absent for an unauthenticated read.

Bases: StrEnum