docs: synchronize deployment and tenant security guidance

docs/social-tenant-foundation.md

@@ -44,6 +44,22 @@ ownership record remains.
 create canonical ownership records and therefore must not be used for
 multi-tenant production social publishing.
 
+## API-key and workspace membership authorization
+
+An API key's effective scopes are the credential ceiling; the resolved active
+workspace membership is a second, independent ceiling. Authorization requires
+both to allow the requested scope. A privileged API key therefore cannot
+elevate a viewer membership.
+
+Workspace membership roles map to permission ceilings as follows:
+
+- `owner` and `admin`: all membership scopes, still limited by the API key.
+- `member` and `service`: the configured `operator` scope set.
+- `viewer`: the configured read-only `viewer` scope set.
+
+The role mapping is applied from the server-resolved `api_key_principals`
+membership, never from a client-supplied workspace or role field.
+
 ## PostgreSQL role separation
 
 Apply all security and social migrations with a controlled administrative