# Magistrate

Magistrate turns a location rule into a decision you can check. You describe the rule in the [Magistrate Studio](https://magistrate.octetproof.com/), for example "only users in Austria" or "nobody in a country under embargo". Magistrate decides each request against that rule, using location proofs from the Octet Mobile SDK, and returns a signed answer.

:::warning[You enforce the decision]

Octet gives you the tools to define a location policy and a signed proof of where a device was. Magistrate returns your policy's answer with a signed receipt. It does not block, allow or change anything in your app or on your servers. Your backend verifies the receipt and decides what happens to the request. If your backend ignores the answer, nothing is enforced.

:::

## Why Magistrate

Many apps have to know where a user is before they allow something: a payment from a sanctioned country, a game in a jurisdiction where it isn't licensed, content outside its rights region. A GPS reading or an IP address is easy to fake, and a yes or no that your app reports is only as trustworthy as the device it runs on.

Magistrate answers the question with evidence instead of a claim:

- **An attested location proof.** The Octet Mobile SDK makes the proof on the device and signs in with hardware attestation, so the answer comes from a genuine install of your app.
- **A signed policy.** The device verifies the policy before it uses it, and never uses one that doesn't verify.
- **A signed receipt.** Every decision comes with a receipt that your backend checks with Octet's published keys, so you act on the receipt, not on what the app reports.
- **Fail-closed.** Without a current proof the answer is UNKNOWN, with a cause such as "no location fix yet". It is never a guess.

## The parts

| Part | What it is | Who uses it |
|---|---|---|
| **Magistrate Studio** | The web app at [magistrate.octetproof.com](https://magistrate.octetproof.com/) where you write, review and sign a policy | Your product, risk or compliance owner |
| **OPL** | The Octet Policy Language. Every policy the studio writes is an OPL policy, and you can read it in the studio's code pane | Anyone who reviews a policy |
| **Octet policy engine** | Octet's service that holds your signed policy and decides each request against it | Nobody directly. The Magistrate module and your backend talk to it |
| **Magistrate module** | A library for iOS and Android that sits on top of the Octet Mobile SDK and asks the engine for a decision | Your app developers |
| **Decision receipt** | The engine's signed copy of each decision | Your backend developers |

## The answer

Each policy asks one question about where the device is, such as "Is the device in Austria?". The studio shows the answer as **YES**, **NO** or **UNKNOWN**. The engine returns it as `permit` or `deny`, and adds a `cause` when the location could not be settled. [Decision Response](/docs/magistrate/reference/decision/) shows how the two map.

UNKNOWN is never a guess. When the proofs can't settle the question, the policy decides with its fail-safe answer, which is `deny` for every policy the studio writes.

## Get started

![A policy goes from the Magistrate Studio to a signed answer in four steps: build, review, ship and answer.](/docs-art/magistrate/policy-journey.svg){: .docs-anim }

1. [Write a policy in Magistrate](/docs/magistrate/get-started/write-a-policy/).
2. Add the Magistrate module to your [iOS](/docs/magistrate/get-started/ios/) or [Android](/docs/magistrate/get-started/android/) app.
3. [Verify and enforce the decision](/docs/magistrate/get-started/verify-and-enforce/) on your backend.

To read or review a policy, start with the [OPL overview](/docs/magistrate/opl/overview/). For how a request travels through the system, see [How It Works](/docs/magistrate/how-it-works/).

These pages cover Magistrate 0.1.0 for iOS and Android. See the [Changelog](/docs/magistrate/reference/changelog/).