# Enforcer

> Identity and authorization in one system, for applications and AI agents.
> Enforcer signs users in (email OTP, passkeys, wallet sign-in, enterprise SSO),
> holds who they are (tenants, roles, groups), and answers "can this actor do this
> action on this resource" with allow or deny, the reason, and a recorded decision.

Most authorization products are a decision layer only: you hand them a subject id
and they return true or false. Enforcer injects the resolved user or agent into
the policy, so a rule is written over a real accessor object with its roles,
tenant and group memberships already on it. Identity and authorization are one
system, which is why a group a person lands in by passing a check is the same
thing a rule reads.

Every entry below is a section of the single-page field manual at
https://docs.instruxi.dev; the anchors are stable, so you can cite one section
rather than the whole page.

The entire documentation as one markdown file is at
https://docs.instruxi.dev/llms-full.txt. It is about 29 KB, so unlike most
documentation sets it fits in a context window whole. Fetch it once and you have
everything; you do not need to crawl. It carries a source URL comment above each
section so you can cite the page a passage came from.

## Start here

- [What Enforcer is](https://docs.instruxi.dev/#what): what the product does and who it is for.
- [Core concepts](https://docs.instruxi.dev/#concepts): tenant, person vs user, groups, auth methods, modules.
- [See how it works](https://docs.instruxi.dev/#how): the walkthrough video and the front-desk analogy.

## Build

- [Quickstart](https://docs.instruxi.dev/#quickstart): sign in, get a token, create a group, flip a gate.
- [Recipes](https://docs.instruxi.dev/#recipes): common tasks as copy-paste calls.
- [Auth model](https://docs.instruxi.dev/#auth-model): which credential to use where, and what each one carries.

## Reference

- [API reference](https://docs.instruxi.dev/#api): every endpoint grouped by area.
- [Worked reference](https://docs.instruxi.dev/#api-worked): the ten operations you will actually use, each with what it does and the exact response shape, generated from the live spec.
- [Errors](https://docs.instruxi.dev/#errors): the error slugs the API returns and what to do about each.
- [Modules and pricing](https://docs.instruxi.dev/#modules): what is free and what is metered.
- [FAQ](https://docs.instruxi.dev/#faq)

## For AI agents

- [Authorization for AI agents](https://docs.instruxi.dev/#agents): giving an agent its own identity and gating what it may do.
- [MCP server authorization](https://docs.instruxi.dev/#mcp): checking every tool call against policy.

## API

Base URL for every path below:

    https://api.instruxi.dev/api/v1/enforcer

- OpenAPI spec (Swagger 2.0): https://api.instruxi.dev/api/v1/enforcer/swagger/doc.json
- Swagger UI: https://api.instruxi.dev/api/v1/enforcer/swagger/
- Health, no credential needed: GET /health

The decision call:

    POST /authz/check
    { "action": "issue",
      "resource": { "type": "payment", "id": "...", "owner_id": "...", "tenant_id": "..." },
      "contexts": { "amount": 820 } }

    -> { "success": true, "allow": false, "reason": "..." }
    # policy_id is echoed back only when you sent one

The caller's identity comes from the bearer token, so do not send it. Deny is the
a decision matching nothing is refused, but a
built-in baseline already allows callers to read and write rows they own, regardless of
the action name, plus groups and group types in their tenant, their own audit events and
global policies. Admins get everything. Name a `policy_id` to have your rule decide the
call instead; a named policy REPLACES the built-in decision rather than adding to it.
`contexts` is only passed to the policy when you name a `policy_id`. On /authz/check the
resource is a description you send and is never looked up, so resolve `owner_id` and
`tenant_id` in your own application, never from the caller.

Rules:

    GET  /policies              list (each has `active`)
    POST /policies              create; leave `active: false` until watched
    PUT  /policies/{id}         switch `active` on or off
    GET  /audit-events          identity and admin trail, NOT decisions
    POST /me/policy             a rule your OWN account puts on itself
    POST /me/policy/{v}/activate   make that version live

An account policy needs only the caller's own token, so any account including an
agent can write one. It may ONLY deny: `allow` is rejected, because an account
cannot grant itself anything. It runs after platform and tenant policy, so a deny
there refuses what they allowed. A tenant-wide policy still needs tenant admin.

## Set me up

- [Agent setup instructions](https://docs.instruxi.dev/setup): point an agent at this page and it connects the MCP server, gets a sandbox token and protects something in the user's own codebase, end to end. "Fetch and follow https://docs.instruxi.dev/setup" is enough. Same instructions as raw markdown at https://docs.instruxi.dev/prompt.md if your fetcher prefers it.

## Tools for agents

- [Enforcer MCP server](https://api.instruxi.dev/mcp): the API as tools, over Streamable HTTP. Listed in the official MCP registry as `dev.instruxi.enforcer/v3`. Add it with `claude mcp add --transport http enforcer https://api.instruxi.dev/mcp` and send an Enforcer API key as `X-API-Key`. Any client that speaks Streamable HTTP works with the same URL.
- [OpenAPI spec](https://api.instruxi.dev/api/v1/enforcer/swagger/doc.json): Swagger 2.0, every operation, if you would rather generate a client than use the MCP.
- Agent skills: in progress. The published set at github.com/instruxi-io/enforcer-skills targets the previous major version and should not be used against v3.

## Rules of thumb

- Never write permission logic into the application. The application asks; Enforcer decides.
- Prefer a group over a list of names in a rule. Groups survive people joining and leaving.
- Cross-tenant access is refused by the engine and is not a setting.
- Create every rule with `active: false`, watch it, then switch it on.

## Pages

- https://docs.instruxi.dev/quickstart - sign in and get a first allow and deny
- https://docs.instruxi.dev/concepts - accounts, tenants, roles, groups, policies
- https://docs.instruxi.dev/auth-model - the three credentials and which calls each is for
- https://docs.instruxi.dev/agent-authorization - authorization for AI agents
- https://docs.instruxi.dev/mcp-authorization - authorizing MCP server tool calls
- https://docs.instruxi.dev/recipes - copyable answers for the first week
- https://docs.instruxi.dev/error-reference - every error slug, cause and fix
- https://docs.instruxi.dev/setup - one-page setup for an agent
- https://enforcer.instruxi.dev/authorization-denial-reasons - returning a reason with a decision
- https://enforcer.instruxi.dev/best-authorization-tools - the category by architecture