# Permissions

URL: /code/platform/permissions · Id: `capability:permissions`

> Permissions grant each Role a Verb on a Noun in a scope, check every Action before it runs, and narrow unused grants nightly.

[Permissions](/business/nouns/permission) decide what every caller may do: a Permission grants a [Role](/business/nouns/role) one [Verb](/business/nouns/verb) on one [Noun](/business/nouns/noun) in a scope. Every [Action](/business/nouns/action) is checked against them before it runs.

## Contract
- A [Worker](/business/nouns/worker), human or agent, holds Permissions only through the Roles it fills. Owner, admin, member and viewer are presets.
- A [Customer](/business/nouns/customer) acts by [Entitlement](/business/nouns/entitlement), granted by an accepted [Offer](/business/nouns/offer). An agent acts for a person by [Mandate](/business/nouns/mandate): standing, expiring and revocable.
- The check runs where the Verb executes, on every call, scheduled and internal ones included. Hiding a button is never the enforcement.
- A Permission can carry a [Limit](/business/nouns/limit), such as refunds up to $200 a day.
- Narrowing takes effect at once. Widening is a [Change](/business/nouns/change) that needs an [Approval](/business/nouns/approval), and no agent widens its own Role or raises its own Limit.
- An agent's key for a [Task](/business/nouns/task) holds its Role's Permissions, narrowed to the records the Task names.
- Each night, a grant unused for 30 days narrows by Change. The Role's owner restores it with one Approval.
- `Permission.check` explains any decision: allowed or refused, and the rule that decided.

## Verbs
| Verb | Object | Event |
| --- | --- | --- |
| [Permission.create](/business/nouns/permission/create) | [Permission](/business/nouns/permission) | `Permission.created` |
| [Permission.list](/business/nouns/permission/list) | [Permission](/business/nouns/permission) | None. |
| [Mandate.authorize](/business/nouns/mandate/authorize) | [Mandate](/business/nouns/mandate) | [`Mandate.authorized`](/business/events/Mandate.authorized) |
| [Mandate.revoke](/business/nouns/mandate/revoke) | [Mandate](/business/nouns/mandate) | [`Mandate.revoked`](/business/events/Mandate.revoked) |
| [Thing.share](/business/nouns/thing/share) | [Thing](/business/nouns/thing) | [`Thing.shared`](/business/events/Thing.shared) |

## Interfaces
- [API](/code/api/reference)
- [SDK](/code/sdk/reference)
- [CLI](/code/cli/reference)
- [MCP](/code/mcp/reference)

## Example
```ts
import { $ } from 'startup-builder'

// A tutoring marketplace asks whether its support agent may refund a $340 lesson pack.
// Run with the agent's key, try passes every gate and stores nothing.
const preview = await $.try.Order.refund({ order: 'order_1842', reason: 'Lesson pack unused' }).settled
// preview.status: 'pending', with an Approval to open (support: Order.refund up to $200/day)
```