> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/authorization-roles-and-entitlements.md).

# Authorization, roles & entitlements

RBAC, route/resource access, plan entitlements, feature state and policy-driven authorization for SONIC API operations.

> **Preview contract** — Authorization and entitlement policies are still under construction and are not fully production-tested until explicitly marked **Live/Verified**.

SONIC separates authentication, authorization, route access and SaaS entitlement instead of collapsing them into a single boolean.

## Context dependency

```
SIGNED SESSION
      ↓
AUTH CONTEXT
      ↓
+--------------------+
|                    |
ACCESS CONTEXT      SAAS ME
|                    |
route policy         subscription
workspace scope      entitlements
feature access       feature flags
```

* `GET /api/v1/auth/context` describes sanitized session authority.
* `GET /api/v1/access/context?path=<internal-path>` evaluates one requested internal path/resource.
* `GET /api/v1/saas/me` describes workspace subscription, entitlements, effective permissions and feature flags.

## Evaluation order

```
Authenticated?
→ correct tenant/workspace?
→ membership active?
→ route/resource policy matched?
→ feature enabled?
→ product entitlement included?
→ permission granted?
→ resource scope valid?
→ workflow transition valid?
→ extra verification/approval satisfied?
→ ALLOW
```

A failed entitlement check may lead the product UI to an upgrade surface. A failed permission check is an authorization failure and must not be rewritten as a billing error.

## Roles

Canonical role templates include Owner, Admin, Project Lead, Creator, Collaborator, Finance, Analyst, Support and Viewer. Role assignments can be workspace-scoped or project-scoped.

## Permissions

Use `resource.action` identifiers such as:

```
project.read
project.update
project.publish
track.generate
marketplace.create_listing
reward.allocate
reward.claim
reward.reconcile
treasury.read
treasury.manage
audit.read
```

Where needed, policy can further scope a grant to `own`, `assigned`, `project`, `workspace` or privileged `any`.

## Entitlements

Plan entitlements describe product availability, for example `ai.basic`, `ai.pro_models`, `collaboration.enabled`, `analytics.advanced` or `marketplace.sell`.

Entitlements never grant administrative authority by themselves. A workspace can be entitled to a feature while an individual member still lacks permission to operate it.

## Route/resource access

`GET /api/v1/access/context?path=<internal-path>` is the route/resource access contract. Its answer is scoped to the requested normalized internal path and must not be reused as blanket authorization for other resources or money-moving operations.

Example failure classes remain distinct:

* `ACCESS_DENIED` — permission/resource policy failure;
* `WORKSPACE_ACCESS_DENIED` — workspace membership/scope failure;
* `SUBSCRIPTION_REQUIRED` — subscription gate;
* `ENTITLEMENT_REQUIRED` — product entitlement absent;
* `FEATURE_DISABLED` — feature flag/environment policy disabled.

## Explicit deny and state machines

A broad role cannot bypass invalid domain state. For security-sensitive policies, explicit deny rules take precedence over allow rules.

## Cache invalidation

Access decisions must be invalidated on role/permission/membership changes and on any route policy, entitlement, subscription or feature-flag change relevant to the decision. Do not publicly cache route-access decisions.

## AI tools

Sonic AI tool calls use the same authorization service as direct application/API operations. Changing the model/provider must never change the user's authority.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/api-reference/authorization-roles-and-entitlements.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.