# Permissions and topics (/apps/permissions)

These tables are built from the platform contracts on every docs build, so they always match what the manifest validator accepts.

## Permissions [#permissions]

An app lists permission ids in `permissions.required` and `permissions.optional` of `poltura.app.json`, each with a purpose. These are the same permissions merchants give their team members, so a merchant reads the same label at install time as in their team settings. Write permissions change only the fields named in the [App API](/api/app) reference. Installation storage and the `app.*` lifecycle webhooks need no permission.

The full catalogue, with labels and descriptions in English and Hungarian, is served at `GET https://api.poltura.com/v1/access/catalog?locale=en` (or `locale=hu`).

| Permission | Access | What merchants see |
| --- | --- | --- |
| `orders.read` | Read | **See orders** See orders, their items, payments and fulfilments |
| `orders.write` | Write | **Change orders** Edit orders, create fulfilments and returns |
| `orders.refund` | Write | **Refund orders** Refund payments |
| `products.read` | Read | **See products** See products, variants, prices, stock and collections |
| `products.write` | Write | **Edit products** Create and edit products, variants, prices, stock and collections |
| `products.publish` | Write | **Publish products** Put products on the storefront and take them down |
| `customers.read` | Read | **See customers** See customers, their contact details, addresses and order history |
| `customers.write` | Write | **Change customers** Create and edit customers, their addresses and groups |
| `promotions.read` | Read | **See discounts** See discounts, promotions and their rules |
| `promotions.write` | Write | **Change discounts** Create and change discounts and promotions |
| `content.read` | Read | **See content** See pages, blog posts and guides |
| `content.write` | Write | **Change content** Write and edit pages, blog posts and guides |
| `media.read` | Read | **See media** See the store’s images, videos and files |
| `media.write` | Write | **Upload and edit media** Upload, replace and edit images, videos and files |
| `media.delete` | Write | **Delete media** Delete images, videos and files nothing uses any more |
| `settings.read` | Read | **See store settings** See the store’s name, languages, currencies, regions and shipping |
| `settings.write` | Write | **Change store settings** Change the store’s name, languages, currencies, regions and shipping |
| `imports.read` | Read | **See imports and their reports** See imports from other platforms and files, and their reports |
| `imports.write` | Write | **Connect shops and run imports** Connect another shop and import its products, customers and orders |
| `integrations.read` | Read | **See apps** See connected apps and their settings |
| `integrations.write` | Write | **Connect and set up apps** Connect apps and change their settings |
| `apps.install` | Write | **Install apps** Install and remove apps, and choose the stores and permissions each one gets |
| `feeds.read` | Read | **See feeds** See product feeds for comparison sites and marketplaces, and which products they list |
| `feeds.write` | Write | **Set up and change feeds** Set up product feeds and change their rules |
| `team.read` | Read | **See the team** See the organization’s members and their roles |
| `organization.settings.write` | Write | **Change organization settings** Change the organization’s name and settings |
| `projects.manage` | Write | **Create and delete stores** Create new stores in the organization and delete existing ones |
| `domains.read` | Read | **See domains** See the organization’s domains and their DNS status |
| `domains.manage` | Write | **Add and change domains** Add, connect and change domains, and point them at stores |
| `billing.read` | Read | **See invoices and plans** See invoices, plans, add-ons and usage |
| `billing.accounts.manage` | Write | **Manage billing accounts** Create billing accounts and change their billing details |
| `theme.read` | Read | **See the theme** See the storefront theme and its settings |
| `theme.write` | Write | **Change the theme** Change the storefront theme, its sections and settings |
| `theme.code.write` | Write | **Edit theme code** Change theme code files, styles and assets in a theme draft |
| `theme.publish` | Write | **Publish the theme** Make a theme draft live for shoppers, or roll the live theme back |
| `storefront.status.read` | Read | **See the store status and password** See whether the store is open, closed or behind a password, and the password |
| `storefront.status.manage` | Write | **Open, close and set the store password** Open and close the store, and set or remove its password |
| `inbox.read` | Read | **Read messages** Read customer messages and conversations |
| `inbox.reply` | Write | **Reply to messages** Reply to customer messages and assign conversations |
| `inbox.manage` | Write | **Change inbox settings** Change the inbox’s channels, rules and settings |
| `inbox.ai.use` | Write | **Draft replies with AI** Draft replies to customers with AI |
| `mail.read` | Read | **See sent emails** See the emails the store sent and whether they arrived |
| `mail.content.read` | Read | **Open sent email content** Open what a sent email said |
| `mail.resend` | Write | **Resend sent emails** Send an email the store sent once more |
| `ai.assistant.use` | Write | **Use the AI assistant** Ask the AI assistant for help in the admin |
| `ai.coder.use` | Write | **Change the store’s code with AI** Have AI change the storefront’s code |
| `translation.use` | Write | **Translate the store** Translate the store into other languages |

## Webhook topics [#webhook-topics]

Subscribe in `webhooks[]` with a topic and an HTTPS destination. Deliveries are signed with Ed25519; see [Webhooks](/apps/webhooks).

| Resource | Topics |
| --- | --- |
| product | `product.created`, `product.updated`, `product.deleted` |
| order | `order.created`, `order.updated`, `order.paid`, `order.fulfilled`, `order.cancelled` |
| customer | `customer.created`, `customer.updated` |
| inventory | `inventory.updated` |
| app | `app.installed`, `app.updated`, `app.suspended`, `app.uninstalled` |
| installation | `installation.permissions_changed`, `installation.stores_changed` |

## UI targets [#ui-targets]

Native UI workers render into these targets. See [Admin](/apps/admin) and [Storefront](/apps/storefront).

| Surface | Targets |
| --- | --- |
| admin | `admin.page`, `admin.home`, `admin.product`, `admin.collection`, `admin.order`, `admin.customer` |
| storefront | `storefront.home`, `storefront.products`, `storefront.product`, `storefront.cart`, `storefront.checkout`, `storefront.login`, `storefront.register`, `storefront.account`, `storefront.contact`, `storefront.page`, `storefront.layout.header`, `storefront.layout.footer`, `storefront.app-page` |

## Error codes [#error-codes]

Every App API error carries one of these codes.

| Code | Status |
| --- | --- |
| `invalid_input` | 400 |
| `unauthorized` | 401 |
| `forbidden` | 403 |
| `insufficient_scope` | 403 |
| `not_found` | 404 |
| `conflict` | 409 |
| `stale_version` | 412 |
| `quota_exceeded` | 409 |
| `rate_limited` | 429 |
| `payload_too_large` | 413 |
| `unsupported_api_version` | 400 |
| `unavailable` | 503 |