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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.883s · 21.8MB
glibcpy 3.10–3.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.fixRefer 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.fixImplement '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`).fixSwitch 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.fixIf 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.fixAvoid 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.fixConsider 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.
fixInstall 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.
fixSet 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.
fixVerify 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.
fixCheck 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.
fixReview 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.