Skip to main content
Get authorization working in your app in under 10 minutes. You will:
  1. Create an authorization policy.
  2. Add user facts.
  3. Make your first authorization check.

​
What you’ll build

a basic document-sharing system where:
  • Alice (owner) can view and edit the budget document.
  • Bob (viewer) can only view the budget document.

​
How Oso Cloud works

Oso Cloud evaluates authorization requests using two components:
  • Policies — Rules written in Polar defining who can do what.
  • Facts — Data about your users, resources, and relationships.
When a request comes in, Oso Cloud checks the policy against your facts to decide access. A diagram illustrating a policy in Oso

​
Step 1: sign up for Oso Cloud

Create your free account — no credit card required. The Developer tier includes 5 developers and 100 monthly active users.

​
Step 2: create your first policy

Open the Rules Editor and switch to Workbench mode. Screenshot of the Rules Editor

​
Add a resource

Create a Document resource to represent files users can access.
  1. Click the input box next to Add a resource
  2. Type “Document”
  3. Click the + icon
Screenshot of the Rules Editor after adding a Document resource

​
Review the generated policy

Oso Cloud generates a policy with these components: Actor: User (someone requesting access) Resource: Document (the file being protected) Roles: viewer and owner Permissions by role:
  • viewer can view documents
  • owner can view and edit documents

​
Deploy the policy

Click Deploy in the top right to activate your policy. Screenshot indicating how to deploy your policy

​
Add user and role facts

A diagram illustrated user and role data - Oso Facts Facts store the current state of users and resources. In this example: -Alice owns the budget document. -Bob views the budget document.

​
Add Alice as owner

  1. Open the Data tab
  2. Click Add next to has_role ( Actor, "owner", Document )
Screenshot of the Data tab
  1. Enter “alice” as the User ID
  2. Enter “budget-2024” as the document name
  3. Click Add this fact
Screenshot of the interface to add a fact Screenshot pointing to where to input the text for your fact Screenshot pointing to the button to add the fact

​
Add Bob as viewer

  1. Click Add next to has_role ( Actor, "viewer", Document )
  2. Enter “bob” as the User ID
  3. Enter “budget-2024” as the document name
  4. Click Add this fact
Screenshot pointing to where to click to add another Fact. Screenshot point to where to input text for the Fact for Bob. Screenshot pointing to the button to add the new fact You now have a working authorization model.

​
Step 4: test authorization in the console

Test your setup by running authorization decisions in the Oso console. Open the Explain tab to run authorization checks. Screenshot of the Explain tab

​
Test Alice’s access

  1. Enter User:alice view Document:budget-2024 in the Authorize field
  2. Click Run
  3. Result should be ✅ Allowed (Alice is an owner)
Screenshot of Explain tab with inputted text pointing to the Run button

​
Test Bob’s access

Try User:bob edit Document:budget-2024. Result should be ❌ Denied (Bob is only a viewer).

​
Step 5: install the Oso Cloud CLI

Install the Oso Cloud CLI to start making authorization checks.
  • MacOS / Linux
  • Windows
curl -L https://cloud.osohq.com/install.sh | bash

​
Step 6: get your API key

Create an API key to authenticate your application.
  1. Go to API Keys settings
  2. Click Create development API key
  3. Name it “Quickstart”
  4. Select Read-Only for testing
  5. Click Create and copy the key
Screenshot of the interface for API keys Screenshot of the interface for API keys pointing to how to add a new development key. Screenshot guiding through the steps to create a new API key Screenshot pointing to the button to copy an API key.
Store your API key securely as an environment variable. Never commit it to source code.

​
Step 7: set your API key

  • MacOS / Linux
  • Windows
export OSO_AUTH=<your_oso_api_key>

​
Make authorization calls

Make authorization decisions in your application code. Test Alice’s access
  • MacOS / Linux
  • Windows
oso-cloud authorize User:alice edit Document:budget-2024
Test Bob’s access
  • MacOS / Linux
  • Windows
oso-cloud authorize User:bob edit Document:budget-2024
Alice can edit because she’s an owner. Bob cannot edit because he’s only a viewer.

​
Next steps: