# Roles and permissions

What owners, admins, members, viewers and billing users can do in a workspace, and how API keys and OAuth tokens are limited.

Every person in a workspace has exactly one role. The role decides what they can see and change in the dashboard, and in anything that acts as them: the dashboard itself and AI assistants connected to the [MCP server](https://pozy.ai/docs/mcp). API keys have their own permissions instead. Pozy checks the role on the server for every request, so a blocked action fails even if someone calls the API directly with their session.

## The five roles

| Role | Meant for |
| --- | --- |
| Owner | The person responsible for the workspace, its billing and its sign-in rules. |
| Admin | Team leads and developers who run the workspace day to day. |
| Member | People who publish, reply, run ads and automations. |
| Viewer | Clients, stakeholders and anyone who only needs to look. |
| Billing | Finance staff who handle invoices and payment methods. |

## What each role can do

| Area | Owner | Admin | Member | Viewer | Billing |
| --- | --- | --- | --- | --- | --- |
| Posts, accounts, inbox, analytics, ads, automations: view | Yes | Yes | Yes | Yes | No |
| Posts, accounts, inbox, analytics, ads, automations: create and change | Yes | Yes | Yes | No | No |
| API keys, webhooks, logs, connected apps: view | Yes | Yes | Yes | No | No |
| API keys, webhooks: create, change, revoke | Yes | Yes | No | No | No |
| Team: see members | Yes | Yes | Yes | Yes | No |
| Team: invite, remove, change roles | Yes | Yes | No | No | No |
| Activity log | Yes | Yes | No | No | No |
| Welcome screen branding, your own platform apps | Yes | Yes | No | No | No |
| Usage and invoices: view | Yes | Yes | No | No | Yes |
| Payment methods and plan changes | Yes | No | No | No | Yes |
| Single sign-on setup | Yes | No | No | No | No |
| Delete the workspace | Yes | No | No | No | No |

A request a role cannot make returns `403` with `code: "role_forbidden"` and a message that names the role, for example "Your role (viewer) cannot change this."

## Change someone's role

Owners and admins change roles on the **Users** page. Role changes, invites and removals are written to the [activity log](https://pozy.ai/docs/security#logs).

Invitations are sent by email and expire after 7 days. People who join through [single sign-on](https://pozy.ai/docs/security/sso) start as members.

Invitation emails are capped per workspace, team and creator invitations together: 20 a day without a payment method (with at most 50 waiting to be accepted), and 500 a day with one. Without a payment method, the person inviting also needs a confirmed email address. One invitation can be emailed again once an hour. Past a cap you get `429` with `code: "invite_limit_reached"` or `"invite_resend_too_soon"`; create an invite link and share it yourself instead. `POST /v1/invite/tokens` returns `emailSent: false` when the email could not go out, so you know to share the link.

## API keys

API keys are not tied to a role. A key acts for the workspace and is limited by its own settings:

| Setting | Effect |
| --- | --- |
| `scope: "profiles"` with `profileIds` | Only those profiles and their accounts. Anything else returns `403 profile_out_of_scope`. |
| `permission: "read"` | Every write returns `403 read_only_key`. |
| `disabledResourceGroups` | Endpoints in those groups return `403 resource_group_disabled`. |
| `expiresIn` | The key stops working after that many days. |

Some actions need a full-scope, read-write key: managing API keys and changing the welcome screen. See [Authentication](https://pozy.ai/docs/getting-started/authentication).

## OAuth tokens (MCP)

When someone connects an AI assistant through the MCP server, the token acts as that person and carries their role. A viewer's token is read-only, and so is any token the person approved as read-only. Removing someone from the workspace stops their tokens from working there.

## Choosing roles

- Give developers **admin** if they create keys and webhooks. A **member** can see keys and webhooks but not create them.
- Give agency clients **viewer** so they can follow their posts and analytics without changing anything.
- Keep **owner** with one accountable person. Ownership controls billing and single sign-on.

## Endpoints

| Endpoint | What it does |
| --- | --- |
| [`POST /v1/invite/tokens`](https://pozy.ai/docs/api/createInviteToken) | Create invite token |
| [`GET /v1/users`](https://pozy.ai/docs/api/listUsers) | List users |
| [`GET /v1/users/{userId}`](https://pozy.ai/docs/api/getUser) | Get user |