# Security Model Overview

The Security Model defines how identities authenticate to Synqly and how access to resources is authorized. It applies consistently across the Management API, Connector APIs and MCP servers.

The model combines permission sets, resource restrictions, roles, and scoped tokens to enforce least-privilege access while supporting auditing, delegation, and enterprise governance requirements.

If you haven't read [Understanding the Synqly Model](/guides/concepts) yet, start there — it covers organizations, accounts, and members, which the Security Model acts on.

## How authorization is determined

This section explains the RBAC model that the token types are built on. It provides the context needed when designing roles, troubleshooting unexpected access denials, or understanding why a token has a particular level of access.

Synqly's authorization model is built on three building blocks:

Permission sets
**What can you do?**

A named bundle of API actions. Fixed catalogue — you pick, not compose.

Resources
**On which objects?**

Restrict by account ID, label, environment, or integration category.

Roles
**Reusable pairing**

Named combination of permission set + resource restrictions. Bind to members.


```mermaid
flowchart LR
    ps("Permission Set\n(the verbs)")
    res("Resources\n(the nouns)")
    role("Role\n(named combination)")
    member("Member\n(person or service)")

    ps --> role
    res --> role
    role --> member
```

### Permission sets

A permission set is a **named, predefined bundle of API actions**. You pick from a fixed catalogue — you don't assemble one from scratch.

administrator
Full administrative access

viewer
Read-only access across all resources

account-manager
Create and manage accounts, integrations, credentials

member
Minimum access — log in, view own profile, basic status

connect-ui
Power a Connect UI widget — create/delete integrations and credentials only

token-issuer
Issue integration tokens, nothing else

mcp-integrations-use-only
Read accounts/integrations + call Connector APIs

mcp-management
Create/update integrations, no Connector API access

What exactly does a permission set allow?
Don't guess — query the [Permission Sets API](https://docs.synqly.com/api-reference/management/permissionset). It returns the precise list of API actions each set grants.

### Resources

A permission set says *what you can do* — but to *what*? Without a resource restriction, `administrator` means administrator over **everything** in your organization. Resources let you apply restrictions across three dimensions:

- **Organizations** (`resources.organizations`) — restrict by organization ID or label
- **Accounts** (`resources.accounts`) — restrict by account ID, label, or environment
- **Integrations** (`resources.integrations`) — restrict by connector category


Restrict by account ID

```yaml
resources:
  accounts:
    ids: ["account-123", "account-456"]
```

Restrict by label + environment

```yaml
resources:
  accounts:
    labels: ["customer-success-team"]
    environments: ["prod"]
```

When both `labels` and `environments` are specified, both must match — it's **AND** logic, not OR. Valid environment values are `"test"` and `"prod"`.

Restrict by integration category

```yaml
resources:
  integrations:
    categories: ["siem", "ticketing"]
```

Valid category values: `appsec` `assets` `chat` `cloudsecurity` `custom` `edr` `emailsecurity` `endpointmanagement` `identity` `incidentresponse` `operations` `siem` `ticketing` `vulnerabilities`

Restrict by organization

```yaml
resources:
  organizations:
    ids: ["org-123"]
```

Use `*` to grant access to all organizations. You can also restrict by label using `labels: ["enterprise-tier"]`.

### Roles

A role is a **permission set + resource restriction, given a name** so you can reuse it across tokens and members.

See the [Roles API reference](https://docs.synqly.com/api-reference/management/roles) for full create/list operations.

### Members

A role does nothing until it's bound to a **member** — a human user or a service account. A member's effective access is the **union** of all their role bindings.

Multiple role bindings are OR'd, not AND'd
If any one of a member's roles permits an action, that action is permitted. Roles only ever **add** capability — they cannot be used to carve exceptions from each other.

See the [Members API reference](https://docs.synqly.com/api-reference/management/members).

## Why Synqly uses role-based access control

Synqly uses role-based access control (RBAC) to support least-privilege access, resource isolation, and auditability. Instead of granting broad access through shared credentials, RBAC allows permissions to be assigned according to a caller's responsibilities and constrained to specific resources.

| Shared credentials | Role-based access control |
|  --- | --- |
| One credential is used by multiple callers | Each caller receives only the permissions required for its role |
| A credential compromise can expose all accessible resources | Access is limited to the permissions and resource restriction assigned to that role |
| Actions cannot be reliably attributed to an individual caller | Actions are attributed to a specific member, service account, or token |
| Access boundaries depend on how callers use the credential | Access boundaries are enforced by the platform |


A resource restriction is not a convention or expectation about how a caller should behave. It is a platform-enforced boundary that is evaluated on every request.