Reference
/
Client APIs
/
Python

Python Client API

💡

Before going through this guide, make sure you follow the Oso Cloud Quickstart to get your Oso API Key properly set in your environment.

First, install the oso-cloud package on PyPI:

pip install oso-cloud

Instantiating an Oso Cloud Client

The Oso Cloud library works by providing an Oso class which you configure with your Oso Cloud URL:

from oso_cloud import Oso

oso = Oso(url="https://cloud.osohq.com", api_key=YOUR_API_KEY)

# Later:
oso.tell("has_role", user, role, resource)

# Wherever authorization needs to be performed:
if oso.authorize(user, action, resource):
    # Action is allowed

Management API

💡

Under the hood, Oso represents your objects as a TYPE and an ID. Right now, the Python API assumes that each object passed to these methods is either a string or an instance of a class (with a name) and with an id property, which together form a unique type/ID combination.

Add fact: oso.tell(predicate, *args)

Adds a fact named predicate with the provided arguments. Example:

oso.tell("has_role", User("bob"), "owner", Organization("acme"))

Add many facts: oso.bulk_tell([*[predicate, *args]])

Adds many facts at once. Example:

oso.bulk_tell([
    ["has_role", User("bob"), "owner", Organization("acme")],
    ["has_role", User("bob"), "maintainer", Repository("anvil")],
])

Delete fact: oso.delete(predicate, *args)

Deletes a fact. Does not throw an error if the fact is not found. Example:

oso.delete("has_role", User("bob"), "maintainer", Repository("anvil"))

Delete many facts: oso.bulk_delete([*[predicate, *args]])

Deletes many facts at once. Does not throw an error when some of the facts are not found. Example:

oso.bulk_delete([
    ["has_role", User("bob"), "owner", Organization("acme")],
    ["has_role", User("bob"), "maintainer", Repository("anvil")],
])

List facts: oso.get(predicate, *args)

Lists facts that are stored in Oso Cloud. Can be used to check the existence of a particular fact, or used to fetch all facts that have a particular argument:

# Get one fact:
oso.get("has_role", bob, "admin", anvils)
# => [{
#   "predicate": "has_role",
#   "args": [
#     { "type": "User", "id": "bob" },
#     { "type": "String", "id": "admin" },
#     { "type": "Repository", "id": "anvils" }
#   ]
# }]

# List all roles on the `anvils` repo
oso.get("has_role", None, None, anvils)
# => [
#   {
#     "predicate": "has_role",
#     "args": [
#       { "type": "User", "id": "bob" },
#       { "type": "String", "id": "admin" },
#       { "type": "Repository", "id": "anvils" }
#     ]
#   },
#   ... other has_role facts
# ]

Note that None behaves like a wildcard: passing None, None, anvils means "find all facts where anvils is the third argument, regardless of other arguments".

Check API

💡

Under the hood, Oso represents your objects as a TYPE and an ID. Right now, the Python API assumes that objects passed to these methods are instances of a class (with a name) and have an id property, which together form a unique type/ID combination.

Check a permission: oso.authorize(actor, action, resource)

Determines whether or not an action is allowed, based on a combination of authorization data and policy logic. Example:

if not oso.authorize(user, "read", anvils_repository):
    raise Exception("Action is not allowed")

Check authorized resources: oso.authorize_resources(actor, action, resources)

Returns a subset of resources on which an actor can perform a particular action. Ordering and duplicates, if any exist, are preserved. Example:

resources = oso.authorize_resources(user, "read", [anvils_repository, acme_repository])

List authorized resources: oso.list(actor, action, resource_type)

Fetches a list of resources on which an actor can perform a particular action. Example:

repository_ids = oso.list(user, "read", "Repository")

List authorized actions: oso.actions(actor, resource)

Fetches a list of actions which an actor can perform on a particular resource. Example:

actions = oso.actions(user, anvils_repository)

List facts: oso.get(predicate, *args)

Lists facts that are stored in Oso Cloud. Can be used to check the existence of a particular fact, or used to fetch all facts that have a particular argument:

# Get one fact:
oso.get("has_role", bob, "admin", anvils)
# => [{
#   "predicate": "has_role",
#   "args": [
#     { "type": "User", "id": "bob" },
#     { "type": "String", "id": "admin" },
#     { "type": "Repository", "id": "anvils" }
#   ]
# }]

# List all roles on the `anvils` repo
oso.get("has_role", None, None, anvils)
# => [
#   {
#     "predicate": "has_role",
#     "args": [
#       { "type": "User", "id": "bob" },
#       { "type": "String", "id": "admin" },
#       { "type": "Repository", "id": "anvils" }
#     ]
#   },
#   ... other has_role facts
# ]

Note that None behaves like a wildcard: passing None, None, anvils means "find all facts where anvils is the third argument, regardless of other arguments".

Policy API

Update the active policy: oso.policy(policy)

Updates the policy in Oso Cloud. The string passed into this method should be written in Polar. Example:

oso.policy("actor User {}")

Talk to an Oso Engineer

Our team is happy to help you get started with Oso. If you'd like to learn more about using Oso in your app or have any questions about this guide, schedule a 1x1 with an Oso engineer.

Get started with Oso Cloud →

Last updated on May 26, 2022