<img width="1070" alt="GitHub Repo Cover" src="https://github.com/corbado/corbado-php/assets/18458907/aa4f9df6-980b-4b24-bb2f-d71c0f480971">
# Corbado Python SDK
[](./LICENSE)
[](https://apireference.cloud.corbado.io/backendapi/)
[](https://join.slack.com/t/corbado/shared_invite/zt-1b7867yz8-V~Xr~ngmSGbt7IA~g16ZsQ)
The [Corbado](https://www.corbado.com) Python SDK provides convenient access to the [Corbado Backend API](https://apireference.cloud.corbado.io/backendapi-v2/) from applications written in the Python language.
:warning: The Corbado Python SDK is commonly referred to as a private client, specifically designed for usage within closed backend applications. This particular SDK should exclusively be utilized in such environments, as it is crucial to ensure that the API secret remains strictly confidential and is never shared.
:rocket: [Getting started](#rocket-getting-started) | :hammer_and_wrench: [Services](#hammer_and_wrench-services) | :books: [Advanced](#books-advanced) | :speech_balloon: [Support & Feedback](#speech_balloon-support--feedback)
## :rocket: Getting started
### Requirements
- Python 3.8 or later
### Installation
Use the following command to install the Corbado Python SDK:
```bash
pip install passkeys
```
### Usage
To create a Corbado Python SDK instance you need to provide your `Project ID` and `API secret` which can be found at the [Developer Panel](https://app.corbado.com).
```Python
config: Config = Config(project_id="{project_id}", api_secret="{api_secret}")
sdk = CorbadoSDK(config=config)
```
### Examples
A list of examples can be found in the integration tests [here](tests/integration).
## :hammer_and_wrench: Services
The Corbado Python SDK provides the following services:
- `sessions` for managing sessions ([example flask app](https://github.com/corbado/example-passkeys-python-flask))
- `users` for managing users ([examples](tests/integration/test_identifier_service.py))
- `identifiers` for managing login identifiers ([examples](tests/integration/test_user_service.py))
To use a specific service, such as `users`, invoke it as shown below:
```Python
user_service: UserService = sdk.users
```
## :books: Advanced
### Error handling
The Corbado Python SDK raises exceptions for all errors. The following exceptions are thrown:
- `ValidationError` for failed validations (client side)
- `ServerException` for server errors (server side)
- `TokenValidationException` for errors in session service (client side)
- `StandardException` for everything else (client side)
`SessionService` returns a `UserEntity` as a result of token validation. If the token is invalid for any reason,
a `TokenValidationException` is thrown. It provides detailed information on the error.
If no error, is thrown, the `session_token` is valid and you can use the `UserEntity` object.
```Python
try:
user: UserEntity = sdk.sessions.validate_token(session_token)
except TokenValidationException:
# handle error..
pass
```
If the Backend API returns a HTTP status code other than 200, the Corbado Python SDK throws a `ServerException`. The `ServerException`class provides convenient methods to access all important data:
sdk.users.get(user_id="usr-123456789")
```Python
try:
# Try to get non-existing user with ID 'usr-123456789'
sdk.users.get(user_id="usr-123456789")
except ServerException as e:
# Show HTTP status code (404 in this case)
print(f"Status Code: {e.http_status_code}")
# Show request ID (can be used in developer panel to look up the full request
# and response, see https://app.corbado.com/app/logs/requests)
print(f"Request id: {e.request_id}")
# Show full request data
print(f"Request data: {e.request_data}")
# Show runtime of request in seconds (server side)
print(f"Runtime: {e.runtime}")
# Show error type (not_found)
print(f"Error type: {e.error_type}")
# Show full error data
print(f"Full error: {e.error}")
```
## Developer Setup
Create a virtual environment and install packages -
``` console
python3 -m venv venv_name
source venv_name/bin/activate
pip install -r requirements-dev.txt
```
(Add venv_name to "exclude" list in .flake8, otherwise flake8 will lint the generated venv)
Add environment variables for tests (use the test project from secrets repositoty) -
``` console
export CORBADO_API_SECRET=corbado1_123456
export CORBADO_PROJECT_ID=pro-123456
export CORBADO_BACKEND_API="https://backendapi.cloud.corbado.io"
```
# Testing
Run all tests using -
``` console
tox run -e py38
```
The tox tests are configured to run on Python 3.8, 3.9, 3.10, 3.11, 3.12 (you need to remove "-e py38" tox argument)
Run linting and mypy:
``` console
mypy -p corbado_python_sdk --exclude generated --strict --disable-error-code attr-defined
flake8 .
```
# Development notes
Use Version file as single source of truth for version control.
Use VSCode with provided project/extentions configuration .vscode/settings.json
Use the recommended extentions from .vscode/extentions.json and explore their functionality to achieve expected code quality by integration tests:
## :speech_balloon: Support & Feedback
### Report an issue
If you encounter any bugs or have suggestions, please [open an issue](https://github.com/corbado/corbado-python/issues/new).
### Slack channel
Join our Slack channel to discuss questions or ideas with the Corbado team and other developers.
[](https://bit.ly/passkeys-community)
### Email
You can also reach out to us via email at vincent.delitz@corbado.com.
### Vulnerability reporting
Please report suspected security vulnerabilities in private to security@corbado.com. Please do NOT create publicly viewable issues for suspected security vulnerabilities.
Raw data
{
"_id": null,
"home_page": "https://github.com/corbado/corbado-python",
"name": "passkeys",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Corbado, Corbado Python SDK",
"author": "Corbado team",
"author_email": "support@corbado.com",
"download_url": "https://files.pythonhosted.org/packages/b2/06/e37a61d0b7fd914b53fef07a8eb4a913a1b50cb9f4a142a21ed1557194de/passkeys-2.0.0.tar.gz",
"platform": null,
"description": "<img width=\"1070\" alt=\"GitHub Repo Cover\" src=\"https://github.com/corbado/corbado-php/assets/18458907/aa4f9df6-980b-4b24-bb2f-d71c0f480971\">\n\n# Corbado Python SDK\n\n[](./LICENSE)\n[](https://apireference.cloud.corbado.io/backendapi/)\n[](https://join.slack.com/t/corbado/shared_invite/zt-1b7867yz8-V~Xr~ngmSGbt7IA~g16ZsQ)\n\nThe [Corbado](https://www.corbado.com) Python SDK provides convenient access to the [Corbado Backend API](https://apireference.cloud.corbado.io/backendapi-v2/) from applications written in the Python language.\n\n:warning: The Corbado Python SDK is commonly referred to as a private client, specifically designed for usage within closed backend applications. This particular SDK should exclusively be utilized in such environments, as it is crucial to ensure that the API secret remains strictly confidential and is never shared.\n\n:rocket: [Getting started](#rocket-getting-started) | :hammer_and_wrench: [Services](#hammer_and_wrench-services) | :books: [Advanced](#books-advanced) | :speech_balloon: [Support & Feedback](#speech_balloon-support--feedback)\n\n## :rocket: Getting started\n\n### Requirements\n\n- Python 3.8 or later\n\n### Installation\n\nUse the following command to install the Corbado Python SDK:\n\n```bash\npip install passkeys\n```\n\n### Usage\n\nTo create a Corbado Python SDK instance you need to provide your `Project ID` and `API secret` which can be found at the [Developer Panel](https://app.corbado.com).\n\n```Python\nconfig: Config = Config(project_id=\"{project_id}\", api_secret=\"{api_secret}\")\nsdk = CorbadoSDK(config=config)\n```\n\n### Examples\n\nA list of examples can be found in the integration tests [here](tests/integration).\n\n## :hammer_and_wrench: Services\n\nThe Corbado Python SDK provides the following services:\n\n- `sessions` for managing sessions ([example flask app](https://github.com/corbado/example-passkeys-python-flask))\n- `users` for managing users ([examples](tests/integration/test_identifier_service.py))\n- `identifiers` for managing login identifiers ([examples](tests/integration/test_user_service.py))\n\nTo use a specific service, such as `users`, invoke it as shown below:\n\n```Python\nuser_service: UserService = sdk.users\n``` \n\n## :books: Advanced\n\n### Error handling\n\nThe Corbado Python SDK raises exceptions for all errors. The following exceptions are thrown:\n\n- `ValidationError` for failed validations (client side)\n- `ServerException` for server errors (server side)\n- `TokenValidationException` for errors in session service (client side)\n- `StandardException` for everything else (client side)\n\n`SessionService` returns a `UserEntity` as a result of token validation. If the token is invalid for any reason,\na `TokenValidationException` is thrown. It provides detailed information on the error.\nIf no error, is thrown, the `session_token` is valid and you can use the `UserEntity` object.\n\n```Python\ntry:\n user: UserEntity = sdk.sessions.validate_token(session_token)\nexcept TokenValidationException:\n # handle error..\n pass\n```\n\nIf the Backend API returns a HTTP status code other than 200, the Corbado Python SDK throws a `ServerException`. The `ServerException`class provides convenient methods to access all important data:\n sdk.users.get(user_id=\"usr-123456789\")\n\n```Python\n try:\n # Try to get non-existing user with ID 'usr-123456789'\n sdk.users.get(user_id=\"usr-123456789\")\n except ServerException as e:\n # Show HTTP status code (404 in this case)\n print(f\"Status Code: {e.http_status_code}\")\n\n # Show request ID (can be used in developer panel to look up the full request\n # and response, see https://app.corbado.com/app/logs/requests)\n print(f\"Request id: {e.request_id}\")\n\n # Show full request data\n print(f\"Request data: {e.request_data}\")\n\n # Show runtime of request in seconds (server side)\n print(f\"Runtime: {e.runtime}\")\n\n # Show error type (not_found)\n print(f\"Error type: {e.error_type}\")\n\n # Show full error data\n print(f\"Full error: {e.error}\")\n\n```\n## Developer Setup\n\nCreate a virtual environment and install packages -\n``` console\npython3 -m venv venv_name\nsource venv_name/bin/activate\npip install -r requirements-dev.txt\n```\n(Add venv_name to \"exclude\" list in .flake8, otherwise flake8 will lint the generated venv)\n\nAdd environment variables for tests (use the test project from secrets repositoty) -\n``` console\nexport CORBADO_API_SECRET=corbado1_123456\nexport CORBADO_PROJECT_ID=pro-123456\nexport CORBADO_BACKEND_API=\"https://backendapi.cloud.corbado.io\"\n```\n\n# Testing\n\nRun all tests using -\n\n``` console\ntox run -e py38\n```\n\nThe tox tests are configured to run on Python 3.8, 3.9, 3.10, 3.11, 3.12 (you need to remove \"-e py38\" tox argument)\n\nRun linting and mypy:\n``` console\nmypy -p corbado_python_sdk --exclude generated --strict --disable-error-code attr-defined\nflake8 .\n```\n\n# Development notes\n\nUse Version file as single source of truth for version control.\n\nUse VSCode with provided project/extentions configuration .vscode/settings.json\n\nUse the recommended extentions from .vscode/extentions.json and explore their functionality to achieve expected code quality by integration tests:\n\n\n\n## :speech_balloon: Support & Feedback\n\n### Report an issue\n\nIf you encounter any bugs or have suggestions, please [open an issue](https://github.com/corbado/corbado-python/issues/new).\n\n### Slack channel\n\nJoin our Slack channel to discuss questions or ideas with the Corbado team and other developers.\n\n[](https://bit.ly/passkeys-community)\n\n### Email\n\nYou can also reach out to us via email at vincent.delitz@corbado.com.\n\n### Vulnerability reporting\n\nPlease report suspected security vulnerabilities in private to security@corbado.com. Please do NOT create publicly viewable issues for suspected security vulnerabilities.\n",
"bugtrack_url": null,
"license": null,
"summary": "Corbado SDK",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://github.com/corbado/corbado-python"
},
"split_keywords": [
"corbado",
" corbado python sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "95e68374eed0357ab5a48b9e92e0d8272584da021f4528de9decaa3c7288d6d9",
"md5": "269a2166f5d30d9be43011381dc92c99",
"sha256": "8456feb8c437a1d5e1dfedc5b1af40f8cc5b240be4faf42f180afdf4c7da4d9f"
},
"downloads": -1,
"filename": "passkeys-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "269a2166f5d30d9be43011381dc92c99",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 193406,
"upload_time": "2025-01-23T15:01:23",
"upload_time_iso_8601": "2025-01-23T15:01:23.444476Z",
"url": "https://files.pythonhosted.org/packages/95/e6/8374eed0357ab5a48b9e92e0d8272584da021f4528de9decaa3c7288d6d9/passkeys-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b206e37a61d0b7fd914b53fef07a8eb4a913a1b50cb9f4a142a21ed1557194de",
"md5": "211296513e1cb318d9c80e24f60e8c7e",
"sha256": "792b7ee673ef57fb2518796a758f0d76e981e7c26028dfed9503875f3d72ff38"
},
"downloads": -1,
"filename": "passkeys-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "211296513e1cb318d9c80e24f60e8c7e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 77375,
"upload_time": "2025-01-23T15:01:25",
"upload_time_iso_8601": "2025-01-23T15:01:25.709231Z",
"url": "https://files.pythonhosted.org/packages/b2/06/e37a61d0b7fd914b53fef07a8eb4a913a1b50cb9f4a142a21ed1557194de/passkeys-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-23 15:01:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "corbado",
"github_project": "corbado-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "passkeys"
}
JSON
