canonical: https://jentic.com/apis/osohq.com/oso

# Osohq Oso Cloud HTTP API

Oso Cloud is an authorisation-as-a-service offering that decouples authorisation logic from application code. The HTTP API lets services upload Polar policies, write and read facts that describe relationships between actors and resources, and ask permission and authorisation questions in real time. With 20 endpoints across policy, facts, bulk operations, and queries, Oso Cloud handles role-based, relationship-based, and attribute-based access control behind a single REST interface.

## For AI agents

Upload authorisation policies, manage facts, and check whether a user can perform an action on a resource through Oso Cloud. Agents can offload permission decisions instead of hard-coding role checks.

## Scope

Does not handle authentication, user provisioning, or audit log storage - use for authorisation decisions, Polar policy management, and fact storage only.

## Capabilities

- Upload and version Polar authorisation policies
- Insert and delete facts that describe relationships between actors and resources
- Bulk-load and bulk-delete facts in a single request for migrations
- Ask whether a user has permission for a specific action on a resource
- List the actions a user is allowed to perform on a resource
- Read policy metadata to introspect what's currently active

## Use cases

### Centralised Authorisation for Microservices

Engineering teams replace bespoke per-service permission checks with a central Oso Cloud policy. Services post facts (membership, ownership, role assignments) and call the authorisation endpoint to decide each request. The Polar policy lives in one place and updates atomically across all consumers, removing drift between services.

Example prompt: Check whether user 'alice@acme.com' can perform action 'edit' on resource 'document:42' by POSTing the (actor, action, resource) triple to /authorize.

### Relationship-Based Permissions in B2B SaaS

B2B platforms model parent-child relationships such as organisations owning workspaces owning documents. Oso Cloud stores these relationships as facts and the Polar policy traverses them to compute permissions. The /facts endpoints support inserts, deletes, and bulk operations so the relationship graph stays in sync as customers add and remove members.

Example prompt: Add the fact that user 'bob' has role 'admin' in organisation 'org-7' by POSTing the fact tuple to /facts.

### Authorisation Policy as Code

Platform teams ship authorisation changes through their CI pipeline by uploading new Polar policies via POST /policy. Reviewers can diff Polar source between releases, and changes propagate to every consumer once the new version is active. /policy_metadata exposes which version is live and when it was published, supporting safe rollouts and rollbacks.

Example prompt: Upload a new Polar policy by POSTing the policy source to /policy and then verify it via GET /policy_metadata.

### AI Agent Authorisation Gate via Jentic

Customer-facing AI agents that act on behalf of users must check authorisation before each action. Through Jentic, the agent searches for 'check user permission' and Oso Cloud's /authorize endpoint surfaces with its schema; the call is executed with a Bearer key held in the vault. This avoids embedding the Oso Cloud key in the agent prompt and keeps authorisation enforcement consistent with the rest of the platform.

Example prompt: Use Jentic to search 'check whether a user can perform an action', load the POST /authorize schema, and execute it with the actor, action, and resource captured in the conversation.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/policy` | Get the current authorisation policy |
| POST | `/policy` | Upload a new Polar policy |
| GET | `/policy_metadata` | Read policy metadata such as active version |
| POST | `/facts` | Insert a fact |
| DELETE | `/facts` | Delete a fact |
| POST | `/bulk_load` | Bulk-load many facts in one request |
| POST | `/bulk_delete` | Bulk-delete many facts in one request |
| POST | `/bulk` | Run combined bulk operations |

## Key resources

- **Policy** — Polar authorisation policies and their metadata
- **Facts** — Relationship and attribute facts that drive authorisation decisions
- **Bulk** — Batch insert and delete operations across many facts
- **Queries** — Authorisation, list-actions, and list-resources queries

## Why Jentic

- **Setup:** Wiring Oso Cloud by hand means handling its bearer token auth, targeting the api.osohq.com host, and managing your own retries around policy and fact writes. Through Jentic you install once, import the Oso Cloud HTTP API from the API Directory, store the bearer token once, and your agent calls it.
- **Permission scoping:** Oso Cloud identifies resources through fact and policy request bodies rather than URL path ids, so scope by operations: limit the agent to the operations it needs, such as reading the current policy or posting facts, and leave out fact deletion or bulk_delete unless you add them. You choose the allowed set, so a decision-only agent can query authorization without touching stored policy.
- **Credential handling:** Your Oso Cloud bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check an authorization decision' or 'store an authorization fact', and Jentic returns the matching Oso Cloud operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Auth0 Management API** — Auth0 handles authentication and identity; Oso Cloud handles fine-grained authorisation on top of those identities.
- **Ory APIs** — Ory's permission API offers Zanzibar-style relations; Oso Cloud uses Polar for richer rule expression.
- **Okta API** — Okta authenticates workforce users; Oso Cloud authorises what those users can do inside the application.

## FAQ

### What authentication does the Oso Cloud API use?

Oso Cloud uses HTTP Bearer authentication with an API key. Each request includes Authorization: Bearer <api_key>. Through Jentic, the API key is stored encrypted in the vault and injected at call time, so it never appears in the agent's prompt or logs.

### Can I check authorisation for a user with the Oso Cloud API?

Yes. The authorisation question is asked via the API's authorize query, which evaluates the active Polar policy against the (actor, action, resource) triple and returns whether the action is permitted. The same data model also supports list-actions and list-resources queries to enumerate what an actor can do.

### What are the rate limits for the Oso Cloud API?

Rate limits are not declared in the Oso Cloud OpenAPI spec; in practice the service applies plan-based throttling and returns 429 with a Retry-After header when a tenant exceeds its quota. For latency-sensitive paths Oso recommends keeping the local agent SDK alongside Cloud rather than calling the HTTP API on every request.

### How do I add a relationship fact through Jentic?

Through Jentic, search for 'add an Oso Cloud fact', load the POST /facts schema, and execute it with the fact tuple - for example {predicate: 'has_role', args: ['User:alice', 'admin', 'Org:7']}. Jentic injects the Bearer key from the vault.

### Can I bulk-load facts after a data migration?

Yes. POST /bulk_load accepts an array of facts and inserts them in a single request, and POST /bulk_delete removes them in bulk. This is the recommended pattern when synchronising Oso Cloud with another source of truth such as a directory or CRM.

### Is Oso Cloud free to use?

Oso Cloud has a free Developer tier suited for evaluation; production usage is on paid plans tied to monthly authorisation requests and tenant counts. The local Oso agent that pairs with Cloud is open source.

### Can I limit what my agent is allowed to do with the Oso Cloud API?

Yes. Because you run Jentic One yourself, your own rules decide which Oso Cloud operations and credentials the agent can use, and Oso Cloud scopes access by operation rather than by URL path ids. You can allow only the calls the agent needs, such as reading the current policy or posting facts, while leaving out fact deletion, bulk_delete, and policy uploads. That way a decision-only agent can run authorize queries without ever touching stored policy or removing facts.