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.
|
required |
api_key
|
str | None
|
Bearer credential for write operations. Falls back to the
|
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(id, value, *, used_by=None, caller=None)
Stores an already-sealed value under a new object id. Requires a
credential (see api_key/HUSH_HUSH_API_KEY).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
str
|
The new object's id. Must match hush-hush's id 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 id). |
delete_object(id, *, caller=None)
Permanently removes an object. A subsequent get by this id returns a 404 APIError. Requires a credential.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
str
|
The object's id. |
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(id, *, 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 |
|---|---|---|---|
id
|
str
|
The object's id. |
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 id). |
get_object_used_by(id)
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 |
|---|---|---|---|
id
|
str
|
The object's id. |
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 id). |
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)
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
|
Returns:
| Type | Description |
|---|---|
list[AuditLogEntry]
|
Matching audit log entries, oldest first. |
Raises:
| Type | Description |
|---|---|
APIError
|
If the server responds with anything other than 200. |
update_object(id, value, *, caller=None)
Replaces the stored ciphertext for an existing object. The object's id and used-by metadata are unchanged. Requires a credential.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
str
|
The existing object's id. |
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(id, value, *, used_by=None, caller=None)
async
See Client.create_object.
delete_object(id, *, caller=None)
async
See Client.delete_object.
get_object(id, *, caller=None)
async
See Client.get_object.
get_object_used_by(id)
async
health()
async
See Client.health.
query_audit_log(*, object_id=None, caller=None, from_=None, to=None)
async
update_object(id, 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 |
message |
str | None
|
The parsed |
body |
bytes
|
The raw, unparsed response body, for a caller that needs more
than |