update api v1.md to explain authorization

Author: Yoyasp

doc/API/V1.md

@@ -161,8 +161,58 @@ This searches across `hostname`, `sysName`, and `os` for devices.
 
 ## Access Control
 
-- **Devices and Ports** Users with global read access see all resources. Other users only see resources they have been granted access to.
-- **Alert Templates** Users with global read access can view. Only admins can create, update, or delete.
-- **Alert Rules** Users with global read access can view. Only admins can create, update, or delete. Results are scoped to devices the user has access to.
-- **Device Groups** Users with global read access can view. Only admins can create, update, or delete. Results are scoped to groups the user has access to.
-- **Users** Only admins can list all users. Non-admin users can only view their own profile.
+### Authorization flow
+
+Every request runs through the same four stages. It must clear **all** of them or it is
+rejected with the status shown:
+
+```
+  Request + Bearer token
+          │
+  1. Authentication ............... valid Sanctum token?            no → 401 Unauthenticated
+          │ yes (token → user)
+  2. API access permission ........ user has `api.access`?          no → 403 Forbidden
+          │ yes
+  3. Per-action authorization ..... policy allows this verb?        no → 403 Forbidden
+          │ yes                       (viewAny / view / create / update / delete)
+  4. Result scoping ............... record(s) within user's scope?  out of scope → filtered
+          │                                                          (a single show → 404)
+          ▼
+     Response
+```
+
+1. **Authentication** the `auth:sanctum` middleware resolves the token to a user. See [Authentication](#authentication).
+2. **API access permission** the user must hold the `api.access` permission. It is granted to the **admin** and **global-read** roles out of the box; other roles need it added explicitly. Without it, no v1 endpoint is reachable.
+3. **Per-action authorization** each HTTP verb maps to a Laravel policy method on the resource's model: `index → viewAny`, `show → view`, `POST → create`, `PATCH/PUT → update`, `DELETE → delete` (Restify also checks `allowRestify`). Two shortcuts apply: **admins** pass every check, and **global-read** users pass every *read* check (`view*` / `show`).
+4. **Result scoping** even when a user may use an endpoint, the rows they get back are filtered to what they're allowed to see. How that filter works depends on the repository's *flavor* (below). A `show` for an out-of-scope id returns `404`.
+
+### Roles at a glance
+
+| Role | API access | Can read | Can write (create/update/delete) |
+|------|:---:|---|---|
+| **admin** | ✓ | everything | everything |
+| **global-read** | ✓ | everything (read-only) | no (unless a policy allows it) |
+| **user** / custom | only if `api.access` is granted | only resources they're scoped to | only where a policy allows |
+
+### Repository scoping flavors
+
+Stage 4 is implemented per repository. Most resources fall into one of these flavors:
+
+| Flavor | How results are filtered | Example resources |
+|--------|--------------------------|-------------------|
+| **Device-scoped** | To devices the user has access to. | `devices`, `sensors`, `processors`, `storage`, `mempools`, `alerts`, `alert-rules`, `device-groups`, `locations`, `bills`, `inventory`, BGP/OSPF/MPLS peers & tunnels, … (~44 resources) |
+| **Port-scoped** | To ports the user is granted **plus** every port on a device they can see (broader than device access). | `ports`, `port-statistics`, `transceivers`, `ipv4-addresses`, `ipv6-addresses`, `routes`, `port-vlans`, `pseudowires`, … (~19 resources) |
+| **Global** | Not filtered per record visible to anyone who clears stages 1–3 (typically global-read or admin). | `alert-templates`, `poller-groups`, `poller-clusters`, `ipv4-networks`, `ipv6-networks`, `auth-logs`, … |
+| **Owner-scoped** | To the caller's own records. | `users` (admins see all; everyone else sees only their own profile) |
+
+For how a new repository opts into a flavor (the `DeviceScopedRepository` / `PortScopedRepository`
+traits and the `DeviceRelatedModel` / `PortRelatedModel` base models), see
+[Creating API v1 Resources › Access Control Patterns](../Developing/Creating-API-Resources.md#access-control-patterns).
+
+### Per-resource notes
+
+- **Devices and Ports** Global-read users see all; others see only the devices/ports they've been granted.
+- **Alert Templates** Global-read users can view; only admins can create, update, or delete.
+- **Alert Rules** Viewable with global read; only admins can create, update, or delete. Results are scoped to devices the user has access to.
+- **Device Groups** Viewable with global read; only admins can create, update, or delete. Results are scoped to the groups the user can access.
+- **Users** Only admins can list all users; non-admin users can only view their own profile.