# Authentication and Authorization

Authentication identifies a request. Authorization decides whether that actor may perform an operation in a namespace.


# Request actor

Authentication produces an immutable `RequestActor` containing:

- Stable actor identity.
- Provider identities such as `(provider, subject)` pairs.
- Credential scopes.
- Optional namespace restrictions.
- A credential fingerprint for safe audit correlation.

The actor is created once per request and passed through REST request context. Query and command requests use ordinary JSON over authenticated REST. Local execution uses an unrestricted single-user actor and policy; remote execution authenticates each request and applies server policy. Both use namespace-scoped query semantics.


# Scopes

Scopes are separate read and write permissions for namespace, resource template, resource, process template, and process run families. Write permission does not implicitly grant read permission.


# Namespace grants

Multi-user authorization is compiled into an immutable snapshot. Grants bind identities and roles to namespace paths and scopes. Policy evaluation:


*\[Rich HTML output -- view on the documentation site\]*


Evaluation first canonicalizes namespace, applies actor restrictions, matches provider identities, collects namespace and ancestor grants, intersects those grants with credential scopes, and validates the target relationship. Write scope does not imply read scope.

Ancestor grants can make templates and resources visible in descendants. Sibling namespaces remain isolated. Process-run access requires exact namespace context.


# Cross-namespace operations

Namespace creation checks write permission on the parent namespace. Resource copy requires both source read permission and destination write permission. A valid source permission alone cannot authorize a destination write.


# REST query filtering

Authorization visibility is applied before user filters, ordering, pagination, and counts. This prevents unauthorized records from influencing result pages or counts returned by REST query/read endpoints.

Remote query requests are JSON envelopes sent to `POST /api/v1/query` or `POST /api/v1/query/count`. Responses contain only authorized models or counts; authorization never relies on client-side filtering.