# Permissions

Apiera uses role-based access control (RBAC) with organization-level tenancy. Every API request is scoped to an
organization, and your permissions within that organization determine what you can do.

## Organizations

All data in Apiera belongs to an **organization**. Your access token determines which organization's data you can
access, and each organization's data is completely isolated from others.

## Account types

| Type | Description |
|  --- | --- |
| **Human** | A user account. Belongs to one or more organizations as a member. |
| **Client** | A third-party application. Granted access to specific organizations via client grants. |


## Roles and permissions

Access is controlled through **roles**, which bundle a set of **permissions**:

- **Permissions** define specific operations (e.g. the ability to create products or manage webhook subscriptions).
- **Roles** group permissions together (e.g. an "Editor" role that can create and modify products but not delete
them).
- **Organization roles** are assigned per organization. You can have different roles in different organizations.


### Organization membership

Human accounts are linked to organizations through **memberships**. Each membership assigns a role that determines
what the user can do within that organization. A membership can also be marked as `isOwner` for full administrative
access.

Membership states:

| State | Description |
|  --- | --- |
| Awaiting provisioning | Invited but not yet active. |
| Active | Full access according to assigned role. |
| Deactivated | Access suspended. |
| Removed | Membership revoked. |


### Client grants

Client accounts (API integrations) receive access through **grants**:

1. A client grant links the client account to a resource server (API).
2. An organization grant scopes the client to a specific organization with a specific role.
3. The role's permissions determine what the client can do.


This means the same client application can have different permission levels in different organizations.

## How permissions are enforced

Permissions are checked on every API request:

1. Your token is validated (signature, expiration, audience).
2. Your account type and organization membership are resolved.
3. The required permissions for the requested operation are looked up.
4. Your role's permissions are checked against the required permissions.
5. If authorized, the request proceeds. Otherwise, you receive a `403 Forbidden` response.


This check happens server-side before any business logic executes. There is no client-side permission enforcement.

## Common error responses

| Status | Meaning |
|  --- | --- |
| [401 Unauthorized](/problems/unauthorized) | Token is missing, invalid, or expired. |
| [403 Forbidden](/problems/forbidden) | Token is valid but your role lacks the required permission. |