| Name | bws-sdk JSON |
| Version |
0.1.4
JSON |
| download |
| home_page | None |
| Summary | pure python implimentation of the bw secrets api |
| upload_time | 2025-07-17 19:35:16 |
| maintainer | None |
| docs_url | None |
| author | rippleFCL |
| requires_python | >=3.13 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# BWS SDK (Bitwarden Secrets SDK)
A pure Python implementation of the Bitwarden Secrets Manager API, allowing secure access to and management of Bitwarden secrets.
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/)
## Overview
BWS SDK provides a simple, Pythonic interface to interact with the Bitwarden Secrets Manager. It handles authentication, decryption, and secure communication with the Bitwarden API, allowing you to easily integrate Bitwarden Secrets into your Python applications.
## Features
- Secure authentication with Bitwarden Secrets Manager
- Automatic decryption of secrets (encryption not yet supported)
- Optional state persistence for improved performance
- Support for different Bitwarden regions
- Synchronization capabilities for efficient secret updates
- Comprehensive error handling
## Installation
```bash
# Using pip
pip install bws-sdk
# Using poetry
poetry add bws-sdk
```
## Quick Start
```python
from bws_sdk import BWSecretClient, Region
from datetime import datetime
# Define the Bitwarden region
region = Region(
api_url="https://api.bitwarden.com",
identity_url="https://identity.bitwarden.com"
)
# Create a client instance with your access token
# Optionally provide a state file path for token persistence
client = BWSecretClient(
region=region,
access_token="your-access-token",
state_file="./path/to/state.file" # Optional
)
# Retrieve a secret by ID
secret = client.get_by_id("your-secret-id")
print(f"Secret key: {secret.key}")
print(f"Secret value: {secret.value}")
# Sync secrets updated since a specific time
last_sync_date = datetime.fromisoformat("2025-01-01T00:00:00")
updated_secrets = client.sync(last_sync_date)
for secret in updated_secrets:
print(f"Updated secret: {secret.key}")
```
## API Reference
### `BWSecretClient`
The main client class for interacting with the Bitwarden Secrets Manager API.
#### Constructor
```python
BWSecretClient(region: Region, access_token: str, state_file: str | None = None)
```
- `region`: A `Region` object specifying the API endpoints
- `access_token`: Your Bitwarden access token
- `state_file`: Optional path to a file for persisting authentication state
#### Methods
- `get_by_id(secret_id: str) -> BitwardenSecret`: Retrieves a secret by its ID
- `sync(last_synced_date: datetime) -> list[BitwardenSecret]`: Retrieves secrets updated since the specified date
> **Note**: The SDK currently only supports decryption of secrets. Methods for creating and encrypting new secrets are planned for future releases.
### `Region`
A class representing a Bitwarden region configuration.
```python
Region(api_url: str, identity_url: str)
```
- `api_url`: The base URL for the region's API endpoint
- `identity_url`: The URL for the region's identity service
### Error Types
- `UnauthorisedError`: Raised when authentication fails
- `InvalidTokenError`: Raised when the provided token is invalid
- `SecretParseError`: Raised when a secret cannot be parsed or decrypted
- `HmacError`: Raised when MAC verification fails during decryption
## Examples
### Using Environment Variables for Secrets
```python
import os
from bws_sdk import BWSecretClient, Region
# Get access token from environment variable
access_token = os.environ.get("BITWARDEN_ACCESS_TOKEN")
# Define the region
region = Region(
api_url="https://api.bitwarden.com",
identity_url="https://identity.bitwarden.com"
)
# Create the client
client = BWSecretClient(region, access_token)
# Retrieve a secret
secret = client.get_by_id(os.environ.get("SECRET_ID"))
print(f"Retrieved secret: {secret.key}")
```
### Error Handling
```python
from bws_sdk import BWSecretClient, Region, UnauthorisedError, SecretParseError
region = Region(
api_url="https://api.bitwarden.com",
identity_url="https://identity.bitwarden.com"
)
try:
client = BWSecretClient(region, "your-access-token")
secret = client.get_by_id("your-secret-id")
print(f"Secret retrieved: {secret.key}")
except UnauthorisedError:
print("Authentication failed. Please check your access token.")
except SecretParseError:
print("Failed to parse or decrypt the secret.")
except Exception as e:
print(f"An unexpected error occurred: {str(e)}")
```
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## References
- [Bitwarden Secrets Manager Documentation](https://bitwarden.com/help/secrets-manager/)
Raw data
{
"_id": null,
"home_page": null,
"name": "bws-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": null,
"author": "rippleFCL",
"author_email": "github@ripple.contact",
"download_url": "https://files.pythonhosted.org/packages/9b/d5/342ec998342894de13a0dd9a16d42964589af5680bbbf307899af65bbce8/bws_sdk-0.1.4.tar.gz",
"platform": null,
"description": "# BWS SDK (Bitwarden Secrets SDK)\n\nA pure Python implementation of the Bitwarden Secrets Manager API, allowing secure access to and management of Bitwarden secrets.\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/)\n\n## Overview\n\nBWS SDK provides a simple, Pythonic interface to interact with the Bitwarden Secrets Manager. It handles authentication, decryption, and secure communication with the Bitwarden API, allowing you to easily integrate Bitwarden Secrets into your Python applications.\n\n## Features\n\n- Secure authentication with Bitwarden Secrets Manager\n- Automatic decryption of secrets (encryption not yet supported)\n- Optional state persistence for improved performance\n- Support for different Bitwarden regions\n- Synchronization capabilities for efficient secret updates\n- Comprehensive error handling\n\n## Installation\n\n```bash\n# Using pip\npip install bws-sdk\n\n# Using poetry\npoetry add bws-sdk\n```\n\n## Quick Start\n\n```python\nfrom bws_sdk import BWSecretClient, Region\nfrom datetime import datetime\n\n# Define the Bitwarden region\nregion = Region(\n api_url=\"https://api.bitwarden.com\",\n identity_url=\"https://identity.bitwarden.com\"\n)\n\n# Create a client instance with your access token\n# Optionally provide a state file path for token persistence\nclient = BWSecretClient(\n region=region,\n access_token=\"your-access-token\",\n state_file=\"./path/to/state.file\" # Optional\n)\n\n# Retrieve a secret by ID\nsecret = client.get_by_id(\"your-secret-id\")\nprint(f\"Secret key: {secret.key}\")\nprint(f\"Secret value: {secret.value}\")\n\n# Sync secrets updated since a specific time\nlast_sync_date = datetime.fromisoformat(\"2025-01-01T00:00:00\")\nupdated_secrets = client.sync(last_sync_date)\nfor secret in updated_secrets:\n print(f\"Updated secret: {secret.key}\")\n```\n\n## API Reference\n\n### `BWSecretClient`\n\nThe main client class for interacting with the Bitwarden Secrets Manager API.\n\n#### Constructor\n\n```python\nBWSecretClient(region: Region, access_token: str, state_file: str | None = None)\n```\n\n- `region`: A `Region` object specifying the API endpoints\n- `access_token`: Your Bitwarden access token\n- `state_file`: Optional path to a file for persisting authentication state\n\n#### Methods\n\n- `get_by_id(secret_id: str) -> BitwardenSecret`: Retrieves a secret by its ID\n- `sync(last_synced_date: datetime) -> list[BitwardenSecret]`: Retrieves secrets updated since the specified date\n\n> **Note**: The SDK currently only supports decryption of secrets. Methods for creating and encrypting new secrets are planned for future releases.\n\n### `Region`\n\nA class representing a Bitwarden region configuration.\n\n```python\nRegion(api_url: str, identity_url: str)\n```\n\n- `api_url`: The base URL for the region's API endpoint\n- `identity_url`: The URL for the region's identity service\n\n### Error Types\n\n- `UnauthorisedError`: Raised when authentication fails\n- `InvalidTokenError`: Raised when the provided token is invalid\n- `SecretParseError`: Raised when a secret cannot be parsed or decrypted\n- `HmacError`: Raised when MAC verification fails during decryption\n\n## Examples\n\n### Using Environment Variables for Secrets\n\n```python\nimport os\nfrom bws_sdk import BWSecretClient, Region\n\n# Get access token from environment variable\naccess_token = os.environ.get(\"BITWARDEN_ACCESS_TOKEN\")\n\n# Define the region\nregion = Region(\n api_url=\"https://api.bitwarden.com\",\n identity_url=\"https://identity.bitwarden.com\"\n)\n\n# Create the client\nclient = BWSecretClient(region, access_token)\n\n# Retrieve a secret\nsecret = client.get_by_id(os.environ.get(\"SECRET_ID\"))\nprint(f\"Retrieved secret: {secret.key}\")\n```\n\n### Error Handling\n\n```python\nfrom bws_sdk import BWSecretClient, Region, UnauthorisedError, SecretParseError\n\nregion = Region(\n api_url=\"https://api.bitwarden.com\",\n identity_url=\"https://identity.bitwarden.com\"\n)\n\ntry:\n client = BWSecretClient(region, \"your-access-token\")\n secret = client.get_by_id(\"your-secret-id\")\n print(f\"Secret retrieved: {secret.key}\")\nexcept UnauthorisedError:\n print(\"Authentication failed. Please check your access token.\")\nexcept SecretParseError:\n print(\"Failed to parse or decrypt the secret.\")\nexcept Exception as e:\n print(f\"An unexpected error occurred: {str(e)}\")\n```\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## References\n\n- [Bitwarden Secrets Manager Documentation](https://bitwarden.com/help/secrets-manager/)\n\n\n\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "pure python implimentation of the bw secrets api",
"version": "0.1.4",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7c27f6df6c74ee9b9df2dfc67aeef5270746ebb12121f66af3d92dc9cddfe6ba",
"md5": "a21421a4eacc22e0490faad97efdc64a",
"sha256": "c4a3016ea8ffad00e421975e9ff73d9ed78381c2226bb351a60cd9c865ff1535"
},
"downloads": -1,
"filename": "bws_sdk-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a21421a4eacc22e0490faad97efdc64a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 9853,
"upload_time": "2025-07-17T19:35:15",
"upload_time_iso_8601": "2025-07-17T19:35:15.607973Z",
"url": "https://files.pythonhosted.org/packages/7c/27/f6df6c74ee9b9df2dfc67aeef5270746ebb12121f66af3d92dc9cddfe6ba/bws_sdk-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9bd5342ec998342894de13a0dd9a16d42964589af5680bbbf307899af65bbce8",
"md5": "ea2541557a93fa25ec68e2c14d8f8cbe",
"sha256": "f38d08671aa99099a881766f946ec58e7acddf0de5fcbc9321875e10abcef597"
},
"downloads": -1,
"filename": "bws_sdk-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "ea2541557a93fa25ec68e2c14d8f8cbe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 7504,
"upload_time": "2025-07-17T19:35:16",
"upload_time_iso_8601": "2025-07-17T19:35:16.869411Z",
"url": "https://files.pythonhosted.org/packages/9b/d5/342ec998342894de13a0dd9a16d42964589af5680bbbf307899af65bbce8/bws_sdk-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 19:35:16",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "bws-sdk"
}
