> ## Documentation Index
> Fetch the complete documentation index at: https://www.osohq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Oso Cloud Quickstart

> Authorize your first user with Oso Cloud

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](https://www.osohq.com/docs/reference/polar/introduction.md) 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](https://mintcdn.com/osoinc/HuMviHxd0NHscL55/images/quickstart/policy-diagram.png?fit=max\&auto=format\&n=HuMviHxd0NHscL55\&q=85\&s=2e80ef2cb3562485797013fbff2de450)

## Step 1: sign up for Oso Cloud

[Create your free account](https://ui.osohq.com/) — 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](https://ui.osohq.com/rules-editor/) and switch to Workbench mode.

![Screenshot of the Rules Editor](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_1.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=7560dd7e14b3d6f76c2f6b8d4b7ebe8f)

### 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](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_2.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=2292a4c59518edac5fe1c6b594126171)

### 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](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_3.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=f3f0fdcdb502874842fe072978147ebe)

## Add user and role facts

![A diagram illustrated user and role data - Oso Facts](https://mintcdn.com/osoinc/HuMviHxd0NHscL55/images/quickstart/facts-diagrams.png?fit=max\&auto=format\&n=HuMviHxd0NHscL55\&q=85\&s=5e61442460c9e80876c2bfb1ca44c540)

**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](https://ui.osohq.com/facts/)
2. Click `Add` next to `has_role ( Actor, "owner", Document )`

![Screenshot of the Data tab](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_4.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=76c1ef3d1528ad9aa900dbb4c830d2e3)

3. Enter "alice" as the User ID
4. Enter "budget-2024" as the document name
5. Click `Add this fact`

![Screenshot of the interface to add a fact](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_5.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=d9c0edb8503ed6d1708744b7fc10f8dd)

![Screenshot pointing to where to input the text for your fact](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_6.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=f4f4f380c685214f4643ddaf622831cc)

![Screenshot pointing to the button to add the fact](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_7.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=465d890ca87b793ecd05d835ae08fcc8)

### 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.](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_8.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=0bf6824eb241a3c4c9bbbdbaf1f4fa2f)

![Screenshot point to where to input text for the Fact for Bob.](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_9.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=786d310071acfffcea48b7e39d64e6c9)

![Screenshot pointing to the button to add the new fact](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_10.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=a7c65c7c83b7de3896886f80d702ec6f)

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](https://ui.osohq.com/explain/) to run authorization checks.

![Screenshot of the Explain tab](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_11.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=b1d5dd257ec80d04d7cd702c113967c4)

### 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](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_12.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=488f9f775386220ef9c681daf1c5f6d3)

### 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.

> [tab] MacOS / Linux
>
> ```bash theme={null}
> curl -L https://cloud.osohq.com/install.sh | bash
> ```

> [tab] Windows
>
> ```bash theme={null}
> > Invoke-WebRequest "https://d3i4cc4dqewpo9.cloudfront.net/latest/oso_cli.exe" -OutFile C:\<your_oso_cli_folder>\oso_cli.exe
> ```

## Step 6: get your API key

Create an API key to authenticate your application.

1. Go to [API Keys settings](https://ui.osohq.com/settings/?api-keys)
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](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_13.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=bc2b4efa5c7ea6bab74b76d3a806d4ba)

![Screenshot of the interface for API keys pointing to how to add a new development key.](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_14.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=4822ad733e5cd11208b4ed1344f720a3)

![Screenshot guiding through the steps to create a new API key](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_15.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=e4568e592533c8d8b3e8d54b1692da66)

![Screenshot pointing to the button to copy an API key.](https://mintcdn.com/osoinc/6cz7kPtI8riSWOc1/images/quickstart/image_16.png?fit=max\&auto=format\&n=6cz7kPtI8riSWOc1\&q=85\&s=29268537e46979fd002210649f73a358)

> [!WARNING]
>
> Store your API key securely as an environment variable. Never commit it to source code.

## Step 7: set your API key

> [tab] MacOS / Linux
>
> ```bash theme={null}
> export OSO_AUTH=<your_oso_api_key>
> ```

> [tab] Windows
>
> ```bash theme={null}
> Set-Item -Path env:OSO_AUTH -Value “<your_oso_api_key>"
> ```

## Make authorization calls

Make authorization decisions in your application code.

**Test Alice's access**

> [tab] MacOS / Linux
>
> ```bash theme={null}
> oso-cloud authorize User:alice edit Document:budget-2024
> ```

> [tab] Windows
>
> ```bash theme={null}
> oso_cloud authorize User:alice edit Document:budget-2024
> ```

**Test Bob's access**

> [tab] MacOS / Linux
>
> ```bash theme={null}
> oso-cloud authorize User:bob edit Document:budget-2024
> ```

> [tab] Windows
>
> ```bash theme={null}
> 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:

* **[Model complex policies](https://www.osohq.com/docs/develop/policies/overview.md)**: learn Polar for advanced rules.
* **[Local Authorization](https://www.osohq.com/docs/develop/facts/local-authorization.md)**: filter directly in your DB for performance.
* **[Sync production facts](https://www.osohq.com/docs/develop/facts/sync-facts.md)**: keep facts up-to-date with application data.
* **[Schedule a technical consultation](https://www.osohq.com/meet-eng?utm_source=cloud-docs\&utm_content=deployment)**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.