{"id":6760,"library":"oso-cloud","title":"Oso Cloud Python Client","description":"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.","status":"active","version":"2.6.0","language":"en","source_language":"en","source_url":"https://www.osohq.com/docs","tags":["authorization","rbac","oso","oso cloud","authorization as a service","microservice authorization","security"],"install":[{"cmd":"pip install oso-cloud","lang":"bash","label":"Install `oso-cloud`"}],"dependencies":[{"reason":"Requires Python 3.8 or newer.","package":"python","optional":false}],"imports":[{"note":"The `oso` library is a deprecated open-source version; `oso_cloud` is the client for the managed service.","wrong":"from oso import Oso","symbol":"Oso","correct":"from oso_cloud import Oso"},{"note":"Used for representing typed values in facts and queries.","symbol":"Value","correct":"from oso_cloud import Value"},{"note":"Type hint for values that can be converted into `oso_cloud.Value`.","symbol":"IntoValue","correct":"from oso_cloud import IntoValue"},{"note":"Type hint for facts that can be converted into `oso_cloud.Fact` (often tuples).","symbol":"IntoFact","correct":"from oso_cloud import IntoFact"}],"quickstart":{"code":"import os\nfrom oso_cloud import Oso, Value\n\n# Initialize Oso Cloud client with an API key\n# Ensure OSO_AUTH environment variable is set or pass it directly:\n# oso = Oso(api_key=os.environ.get('OSO_AUTH', ''))\noso = Oso()\n\n# Define example data\nuser = Value(\"User\", \"alice\")\nrepository = Value(\"Repository\", \"my-repo\")\norganization = Value(\"Organization\", \"acme\")\n\nasync def run_auth_checks():\n    try:\n        # Insert a fact: Alice has the role 'owner' on 'my-repo'\n        await oso.insert((\"has_role\", user, \"owner\", repository))\n        print(f\"Inserted fact: Alice is owner of my-repo.\")\n\n        # Check if Alice can 'read' the 'my-repo' repository\n        # This assumes a policy has been uploaded to Oso Cloud, e.g.,\n        # allow(user: User, \"read\", repo: Repository) if has_role(user, \"owner\", repo);\n        is_allowed = await oso.check(user, \"read\", repository)\n        print(f\"Can Alice 'read' my-repo? {is_allowed}\")\n\n        # Query for all repositories Alice can 'read'\n        # Assumes a policy defining 'allow' rules.\n        readable_repos = []\n        async for result in oso.query(user, \"read\", Value(\"Repository\")):\n            if result.resource:\n                readable_repos.append(result.resource.id)\n        print(f\"Repositories Alice can read: {readable_repos}\")\n\n        # Delete the previously inserted fact\n        await oso.delete((\"has_role\", user, \"owner\", repository))\n        print(f\"Deleted fact: Alice is owner of my-repo.\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n        print(\"Make sure OSO_AUTH environment variable is set with your Oso Cloud API key.\")\n\nimport asyncio\nasyncio.run(run_auth_checks())\n","lang":"python","description":"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."},"warnings":[{"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()`.","message":"Migration 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.","severity":"breaking","affected_versions":"Upgrading from `oso-cloud` v1.x to v2.x"},{"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.","message":"When updating facts or policies in Oso Cloud, direct changes can lead to inconsistent authorization if not handled carefully during the transition period.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The 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`).","severity":"deprecated","affected_versions":"Users of the legacy `oso` library"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"Oso Dev Server v1.2 and later (local development)"},{"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`.","message":"The `*` 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.","severity":"gotcha","affected_versions":"Oso Dev Server v1.15.0 and later (policies interacting with it)"},{"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.","message":"For high-availability production systems, relying solely on the Oso Cloud service might not be sufficient for all failure scenarios.","severity":"gotcha","affected_versions":"All versions (production deployments)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}