> 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/documentation/developers/architecture-and-runtime/identity-access-and-roles.md).

# Identity, Access & Roles

Canonical SONIC v1.0.0 IAM architecture covering Clerk, SONIC identity, workspace roles, Developer access, permissions, entitlements, AAL, session freshness, risk and role-change invariants.

**Version `1.0.0`**

> Authentication ≠ identity ≠ role ≠ entitlement ≠ wallet ownership ≠ transaction authorization.

## Canonical workspace roles

```
OWNER
ADMIN
CREATOR
DEVELOPER
FINANCE
MODERATOR
MEMBER
VIEWER
```

`DEVELOPER` is an engineering/integration role. It is not a Pro/Premium plan and never implies Owner, Admin, Finance, treasury or wallet-signing authority.

## Authorization contract

```
Clerk session
+ SONIC identity
+ workspace membership
+ role grants
+ explicit grants / denies
+ entitlement
+ resource scope
+ AAL / session freshness
+ risk
= authorization decision
```

Every protected mutation re-authorizes server-side. Navigation, React state and hidden buttons are UX projections only.

## Developer baseline

| Capability                      | Baseline                                                      |
| ------------------------------- | ------------------------------------------------------------- |
| Developer Portal                | `DEVELOPER` + `developer.portal.read` + Developer entitlement |
| Read API keys                   | `developer.api_key.read`                                      |
| Manage test keys                | `developer.api_key.manage`                                    |
| Manage live keys                | `developer.api_key.manage` + fresh AAL2                       |
| Manage webhooks                 | `developer.webhook.manage`                                    |
| View usage/logs                 | `developer.usage.read` / `developer.logs.read`                |
| Billing/treasury/wallet signing | not inherited                                                 |

## Role-change safety

Sensitive role changes require `workspace.roles.manage`, fresh AAL2 and a recent session.

The policy also enforces:

* the last active Owner cannot be demoted or removed;
* Admin cannot silently mint Owner/Admin authority;
* self-elevation into Owner authority is blocked;
* cross-workspace role mutation is denied;
* decisions are auditable with request ID and policy version.

## Risk and step-up

```
ALLOW
MONITOR
STEP_UP
REVIEW
DENY
```

`REVIEW` and `DENY` fail closed. `STEP_UP` creates a reverification requirement rather than silently allowing the operation.

## Audit

Record SONIC user/workspace IDs, action, resource, decision, reason, policy version, request ID and timestamp. Never log API-key secrets, Clerk tokens, MFA secrets, wallet signatures, recovery material or ZK witnesses.


---

# 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/documentation/developers/architecture-and-runtime/identity-access-and-roles.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.