Registry / auth-security / oso-cloud

oso-cloud

JSON →
library2.6.0pypypi✓ verified 84d ago

Oso Cloud is an authorization-as-a-service platform. The Python client (`oso-cloud`) provides a convenient wrapper around the Oso Cloud HTTP API, enabling applications to interact with the service for modeling, storing, enforcing, querying, and testing authorization logic using the declarative Polar policy language. The library is currently at version 2.6.0 and demonstrates a healthy release cadence, with the last version released less than a year ago.

pip install oso-cloud
INSTALL
IMPORT
SIG · OSO-CLOUD
O
oso-cloud
auth-securitypythonv2.6.0
Install
2.2s avg
Import
823ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.883s · 21.8MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.2s · import 0.762s · 22MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Oso
from oso_cloud import Oso
from oso import Oso
The `oso` library is a deprecated open-source version; `oso_cloud` is the client for the managed service.
Value
from oso_cloud import Value
Used for representing typed values in facts and queries.
IntoValue
from oso_cloud import IntoValue
Type hint for values that can be converted into `oso_cloud.Value`.
IntoFact
from oso_cloud import IntoFact
Type hint for facts that can be converted into `oso_cloud.Fact` (often tuples).

This quickstart demonstrates how to initialize the `oso-cloud` client, insert authorization facts, and perform permission checks and queries against the Oso Cloud service. It requires an active Oso Cloud account and an API key, which should be set as the `OSO_AUTH` environment variable. The examples assume a basic policy defining roles and permissions (e.g., an owner can read a repository) has been uploaded to your Oso Cloud instance.

import os from oso_cloud import Oso, Value # Initialize Oso Cloud client with an API key # Ensure OSO_AUTH environment variable is set or pass it directly: # oso = Oso(api_key=os.environ.get('OSO_AUTH', '')) oso = Oso() # Define example data user = Value("User", "alice") repository = Value("Repository", "my-repo") organization = Value("Organization", "acme") async def run_auth_checks(): try: # Insert a fact: Alice has the role 'owner' on 'my-repo' await oso.insert(("has_role", user, "owner", repository)) print(f"Inserted fact: Alice is owner of my-repo.") # Check if Alice can 'read' the 'my-repo' repository # This assumes a policy has been uploaded to Oso Cloud, e.g., # allow(user: User, "read", repo: Repository) if has_role(user, "owner", repo); is_allowed = await oso.check(user, "read", repository) print(f"Can Alice 'read' my-repo? {is_allowed}") # Query for all repositories Alice can 'read' # Assumes a policy defining 'allow' rules. readable_repos = [] async for result in oso.query(user, "read", Value("Repository")): if result.resource: readable_repos.append(result.resource.id) print(f"Repositories Alice can read: {readable_repos}") # Delete the previously inserted fact await oso.delete(("has_role", user, "owner", repository)) print(f"Deleted fact: Alice is owner of my-repo.") except Exception as e: print(f"An error occurred: {e}") print("Make sure OSO_AUTH environment variable is set with your Oso Cloud API key.") import asyncio asyncio.run(run_auth_checks())
oso-cloud --version
Debug
Known issues
breakingMigration from `oso-cloud` v1 to v2 involved significant breaking changes. The Fact Management API now uses tuples instead of dictionaries for facts, and methods like `tell` were replaced by `insert`. The Query API was also replaced by a more powerful `build_query()` API, and `authorize_resources` was removed.
fix
Refer to the official migration guide. Key changes include converting fact arguments from dictionaries to `oso_cloud.Value` types and using `insert`/`delete` for fact management. Update query logic to use `oso.build_query()` or `oso.check()`.
affects: Upgrading from `oso-cloud` v1.x to v2.x
gotchaWhen updating facts or policies in Oso Cloud, direct changes can lead to inconsistent authorization if not handled carefully during the transition period.
fix
Implement 'bridge rules' in your Polar policy to map old facts to new ones temporarily. Update application code to write new facts, and then perform a batch migration of existing facts using the Get API and Batch API to ensure consistency. Clean up old facts and bridge rules after migration.
affects: All versions
deprecatedThe standalone `oso` open-source library is deprecated. New projects and existing users are encouraged to migrate to Oso Cloud and its client libraries (`oso-cloud`).
fix
Switch to `oso-cloud` for managed authorization-as-a-service. This involves updating imports, re-evaluating policy management (now typically through Oso Cloud console or CLI), and using the `oso_cloud` client API.
affects: Users of the legacy `oso` library
gotchaThe Oso Dev Server (a local tool often used with `oso-cloud`) had a breaking change in v1.2 related to its data schema. Existing local data might become incompatible.
fix
If using the Oso Dev Server, delete the `.oso` directory (default storage location for local data) before using v1.2 or newer to prevent inconsistencies.
affects: Oso Dev Server v1.2 and later (local development)
gotchaThe `*` literal as a resource identifier was disallowed in Oso Dev Server v1.15.0 to align its behavior with Oso Cloud. Policies using `*` might break.
fix
Avoid using the `*` literal as a resource identifier in Polar policies. If necessary, you can temporarily revert this behavior in the dev server via `OSO_DISABLED_FEATURES=splat-fact-pushback`.
affects: Oso Dev Server v1.15.0 and later (policies interacting with it)
gotchaFor high-availability production systems, relying solely on the Oso Cloud service might not be sufficient for all failure scenarios.
fix
Consider implementing a hybrid deployment model with an Oso Fallback Service. This service acts as a backup, providing authorization responses even if Oso Cloud experiences outages or becomes unreachable.
affects: All versions (production deployments)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'oso_cloud'
The `oso-cloud` Python package has not been installed in your current environment or the Python interpreter cannot find it.
fix
Install the package using pip: `pip install oso-cloud`
Missing OSO API key from environment
The `oso-cloud` client requires an API key for authentication, which is typically provided via the `OSO_AUTH` environment variable, but it was not found or was empty.
fix
Set the `OSO_AUTH` environment variable with your valid Oso Cloud API key before initializing the client. For example: `export OSO_AUTH="<your_api_key>"` (macOS/Linux) or `os.environ['OSO_AUTH'] = "<your_api_key>"` (Python code).
Cannot connect to Oso Cloud
The `oso-cloud` client could not establish a connection to the Oso Cloud service. This can be due to an incorrect service URL, network issues, or the Oso Cloud service being unavailable.
fix
Verify that the `OSO_URL` environment variable (if used) is set to the correct Oso Cloud endpoint (e.g., `https://cloud.osohq.com`) and ensure there are no network restrictions preventing access to the service.
Unauthorized request
The Oso Cloud service rejected your request because the provided API key (via `OSO_AUTH`) is invalid, expired, or does not have the necessary permissions for the requested operation.
fix
Check your `OSO_AUTH` API key for correctness and ensure it has the appropriate permissions configured in the Oso Cloud dashboard for the operations your application is attempting to perform.
Policy failed validation
The Polar policy file you attempted to upload or validate contains syntax errors or logical inconsistencies that prevent Oso Cloud from processing it correctly.
fix
Review the Polar policy file for syntax errors, typos, or logical issues. Use the `oso-cloud policy validate <policy_file.polar>` CLI command or an IDE extension with Polar language support to identify and fix problems.
Upgrade
Version history
2.6.0latest on PyPI · released Mar 30, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.8 or newer.
Agent activity
13 hits · last 30 days
node
10
OpenAI (training)
1
Resources