Client API Reference

`bws_sdk.client.BWSecretClient(region, access_token, state_file=None)`

Client for interacting with the Bitwarden Secrets Manager API.

This class provides methods to retrieve and synchronize secrets from the Bitwarden Secrets Manager. It handles authentication, automatic token refresh, and encryption/decryption of secret data.

Attributes:

Name	Type	Description
`region`	`Region`	The BWS region configuration
`auth`	`Auth`	Authentication handler
`session`	`Session`	HTTP session for API requests

Initialize the BWSecretClient.

Parameters:

Name	Type	Description	Default
`region`	`Region`	The BWS region configuration	required
`access_token`	`str`	The BWS access token for authentication	required
`state_file`	`str \| None`	Optional path to state file for token persistence	`None`

Raises:

Type	Description
`ValueError`	If any of the input parameters are of incorrect type
`InvalidTokenError`	If the access token format is invalid
`BWSSDKError`	If authentication fails during initialization
`SendRequestError`	If the initial authentication request fails
`UnauthorisedTokenError`	If the token is invalid or expired
`ApiError`	If the API returns an error during authentication

`get_by_id(secret_id)`

Retrieve a secret by its unique identifier.

Makes an authenticated request to the BWS API to retrieve a specific secret by its UUID. The returned secret will have its key and value automatically decrypted.

Parameters:

Name	Type	Description	Default
`secret_id`	`str`	The unique identifier (UUID) of the secret to retrieve	required

Returns:

Type	Description
`BitwardenSecretRT \| None`	BitwardenSecret \| None: The retrieved and decrypted secret, or None if not found

Raises:

Type	Description
`UnauthorisedError`	If the response status code is 401 (Unauthorized)
`ValueError`	If the provided secret_id is not a string
`UnauthorisedError`	If the request is unauthorized (HTTP 401)
`ApiError`	If the API returns a non-200 status code
`SecretParseError`	If the secret cannot be parsed or decrypted
`SendRequestError`	If the network request fails
`APIRateLimitError`	If the response status code is 429 (Too Many Requests)

Example

secret = client.get_by_id("550e8400-e29b-41d4-a716-446655440000")
print(f"Secret key: {secret.key}")
print(f"Secret value: {secret.value}")

`raise_errors(response)`

Raise appropriate exceptions based on HTTP response status codes.

Analyzes the HTTP response and raises specific BWS SDK exceptions based on the status code to provide meaningful error handling.

Parameters:

Name	Type	Description	Default
`response`	`Response`	The HTTP response object to analyze	required

Raises:

Type	Description
`UnauthorisedError`	If the response status code is 401 (Unauthorized)
`SecretNotFoundError`	If the response status code is 404 (Not Found)
`APIRateLimitError`	If the response status code is 429 (Too Many Requests)
`ApiError`	For any other non-200 status codes

Note

This method does not return anything when the status code is 200. It only raises exceptions for error status codes.

`sync(last_synced_date)`

Synchronize secrets from the Bitwarden server since a specified date.

Retrieves all secrets that have been created or modified since the provided last synced date. This method is useful for keeping local secret caches up to date with the server state.

Parameters:

Name	Type	Description	Default
`last_synced_date`	`datetime`	The datetime representing when secrets were last synced	required

Returns:

Type	Description
`BitwardenSync`	list[BitwardenSecret]: List of secrets created or modified since the last sync date

Raises:

Type	Description
`ValueError`	If last_synced_date is not a datetime object
`SendRequestError`	If the network request fails
`UnauthorisedError`	If the server returns a 401 Unauthorized response
`ApiError`	If the API returns a non-200 status code
`SecretParseError`	If any secret cannot be parsed or decrypted

Example

from datetime import datetime
last_sync = datetime(2024, 1, 1)
secrets = client.sync(last_sync)
for secret in secrets:
    print(f"Secret: {secret.key} = {secret.value}")

`create(key, value, note, project_ids)`

Create a new secret on the Bitwarden server.

Takes a BitwardenSecretCreate with plaintext key and value, encrypts it, and creates it on the server. Returns the created secret with decrypted values.

Parameters:

Name	Type	Description	Default
`key`	`str`	The key for the secret	required
`value`	`str`	The value for the secret	required
`note`	`str`	A note for the secret	required
`project_ids`	`list[str] \| None`	A list of project IDs the secret is associated with	required

Returns:

Name	Type	Description
`BitwardenSecret`	`BitwardenSecret`	The created secret with decrypted key and value

Raises:

Type	Description
`ValueError`	If the provided secret is not a BitwardenSecretCreate object
`UnauthorisedError`	If the request is unauthorized (HTTP 401)
`ApiError`	If the API returns a non-200 status code
`SecretParseError`	If the secret cannot be encrypted or the response cannot be parsed
`SendRequestError`	If the network request fails

Example

new_secret = BitwardenSecretCreate(
    key="api_key",
    value="secret_value_123",
    note="API key for external service"
)
created_secret = client.create(new_secret)
print(f"Created secret with ID: {created_secret.id}")