# Roles and permissions

> Most operations follow your role in the YoPrint web app, and some don't. How roles work, which operations any member can call, what a refusal looks like, and how to plan around it.

Web page: https://developer.yoprint.com/concepts/roles-and-permissions/

Your API key works with your role on the team in the request's path. **Most operations follow that role. Some don't.** A number of operations let any member of the team call them, whatever their role. They're listed [below](#operations-any-member-can-call), and each operation's reference page states its permission.

## How roles work

- The **team owner** can do everything on the team.
- Every other member has one role on each team. The web app calls roles **Permission Groups**, under team settings.
- A role is a set of permissions, such as creating orders, viewing all orders or only your own, seeing order finances, managing stock or managing settings.
- **Manage Settings** is the team permission (`manage_setting`) that grants administrative control over the shop's setup. Members with this permission can edit team settings, configure integrations (QuickBooks, Shopify, payment gateways), set up webhooks, and read stored secrets (such as payment gateway API secrets and webhook signing secrets). On a plan with advanced permission management, they can also change permission groups. The team owner always has this permission.

New teams start with these roles: Super Admin, Shop Manager, Sales Team, Shop Floor Team and Accounting Team. Creating, changing or deleting a role needs a plan with advanced permission management. Moving a member to another role doesn't.

To see the roles on a team and what each allows, list them:

`GET /v1/api/store/{team_slug}/setting/group` [List permission groups](https://developer.yoprint.com/reference/permission-groups/v1-group-index.md)

To see team members and their roles:

`GET /v1/api/store/{team_slug}/setting/user` [List team members](https://developer.yoprint.com/reference/team-members/v1-user-index.md)

## Roles that see less

Some permissions come in two sizes:

| Permission | Wider                        | Narrower                                      |
| ---------- | ---------------------------- | --------------------------------------------- |
| Orders     | View or update all orders    | View or update only your own orders           |
| Customers  | View or update all customers | View or update only customers assigned to you |

A role with the narrower permission gets fewer records from lists, filters and searches. What "your own" means isn't the same everywhere: the sales order and quote filters return only orders you created, while order search also includes orders you're assigned to. Each reference page states its own rule.

For example, suppose another team member created Order #100 and assigned it to you, while you created Order #101 yourself. If your role can view only its own orders:

- **List sales orders** (the v2 sales order filter): returns only **Order #101** (orders you created). It does not return Order #100.
- **Search orders** (`GET /v2/api/store/your-team/search/orders?q=…`): returns both **Order #100 and Order #101** (orders you created plus orders assigned to you).
- Orders you neither created nor are assigned to are hidden from both.

Roles also differ in whether they can see order and customer finances.

## Operations any member can call

These operations don't check the caller's role, or check less than the web app suggests. Any member's key can call them. Don't rely on a role to stop a key from doing any of this.

| Area                             | What any member's key can do                                                                                                                                                                                                                                                                  |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Customers                        | Create or update a customer by contact (upsert), even one not assigned to them. Upsert contacts. Change contacts, tags and external ids. Changing the email of a contact that gives someone Customer Portal access does check Manage Customers, on every customer the change covers.          |
| Payments                         | Record, change, delete and refund payments. Charge a card through a payment gateway and refund it. Use Square Terminal. Create payment links (allocations). Moving money to and from customer credit does check the role: it needs View Sales Order Pricing and permission to edit the order. |
| Invoices                         | Create and delete invoices, and change their tax selection.                                                                                                                                                                                                                                   |
| Shipping                         | Create shipments and change their status. Get rates. Record labels. Change packages.                                                                                                                                                                                                          |
| Production                       | Change a job's status and production dates. Create, change, assign and delete tasks. Read the job and task boards and calendars, whatever orders the role can see.                                                                                                                            |
| Approvals, comments and messages | Create and send approvals, which email the customer. Edit or delete any comment across the team (including comments written by other team members). Send a message template for any record.                                                                                                   |
| Data exports                     | Export every type, including sales orders, invoices, payments and tax, whatever the role.                                                                                                                                                                                                     |

> **Caution:** Give API keys only to people you'd trust with every operation above, and remove members who no longer need access. These are the documented cases. Each operation's reference page has the exact rule.

## Shipping labels and packages

These shipping actions check the order the shipment belongs to:

| Action                                            | Needs                                                                     |
| ------------------------------------------------- | ------------------------------------------------------------------------- |
| Buy a GoShippo label                              | Permission to view that order: all orders, or your own and assigned ones. |
| Void or remove packages, one at a time or in bulk | Permission to view that order.                                            |
| Delete a shipment                                 | Permission to edit that order.                                            |

So a role that can view orders but not edit them, such as the default Shop Floor Team and Accounting Team roles, can still buy and void labels. Buying a label spends money. See [Ship an order](https://developer.yoprint.com/guides/shipping.md).

## Integration actions

Running an integration's actions needs Manage Settings. Two operations let members without it do a few things:

`PUT /v1/api/store/{team_slug}/setting/external_integration/{id}/public_action` [Search QuickBooks, or sync records to it](https://developer.yoprint.com/reference/integrations/v1-external-integration-public-action.md)

`PUT /v1/api/store/{team_slug}/setting/external_integration/{id}/proxy_request` [Read Shopify orders through the integration](https://developer.yoprint.com/reference/integrations/v1-external-integration-proxy-request.md)

| Action                             | Needs, without Manage Settings                        |
| ---------------------------------- | ----------------------------------------------------- |
| QuickBooks sync of sales orders    | Permission to view every order being synced.          |
| QuickBooks sync of purchase orders | Permission to view every purchase order being synced. |
| QuickBooks customer lookup         | Permission to view all customers.                     |
| QuickBooks vendor lookup           | Permission to view vendors.                           |
| Shopify store order list           | Permission to view all orders.                        |

Anything else through these two, such as the QuickBooks invoice, bill and purchase order lookups, needs Manage Settings.

## Stored secrets

Members without Manage Settings can read team and integration settings, but don't get stored secrets: payment-gateway secret keys and webhook signing secrets come back only to the team owner and people who can manage settings. Stored provider tokens, such as Twilio's or GoShippo's, never come back in integration settings, whoever asks.

## When your role doesn't allow it

YoPrint answers `403` and changes nothing.

```json
{
  "status": 403,
  "success": false,
  "error": {
    "code": "user_is_not_authorized",
    "message": "Your role does not allow this order action. Ask your team owner to review your sales order permissions."
  }
}
```

Other refusals can have a different `code`, or only a `message`, such as settings changes your role doesn't allow, which answer `403` with `{ "message": "Insufficient Permission" }`. Rely on the `403` status. See [Errors](https://developer.yoprint.com/concepts/errors.md).

To fix it, ask the team owner to change your role in the web app, or have a member whose role allows the operation run it with their own key.

## Plan an integration around roles

- Use a key whose role matches what the integration does. An integration that only reads orders doesn't need settings permissions.
- Don't treat a narrow role as a safety net. Check the operations above, and limit who holds keys.
- If an integration's reads look incomplete, check the role before you look for a bug.
- Changing a member's role changes what their key can do at once. You don't need a new key.