# Mailbox authorization Mailbox validates an M7 access token, resolves an active service principal, then checks workspace and project authority for the requested action. Use `Authorization: Bearer ` over HTTPS for authenticated endpoints. Keep client secrets in a trusted server application. ## Obtain a token for the receiving audience Use the M7 SSO [token endpoint](https://m7.org/docs/api/sso.user.m7.org/token.md) with the grant appropriate to your application. Human applications can use [authorization](https://m7.org/docs/api/sso.user.m7.org/authorization.md) or [device authorization](https://m7.org/docs/api/sso.user.m7.org/device-authorization.md). Server applications use their registered machine credentials and client-credentials grant. Follow the issuer's acknowledgement and refresh requirements. Request the receiving audience exactly as configured: ```text https://api.mailbox.service.m7.org/ ``` The trailing slash is significant. Do not substitute the `/v1/` API base or the Mailbox frontend URL. The current service accepts signed `RS512` tokens from `https://sso.user.m7.org` or `id.m7.org` under its configured issuer, audience, trusted-key, and expiry checks. A token readable by your application is not proof that Mailbox will accept it. See the issuer's [token formats](https://m7.org/docs/api/sso.user.m7.org/token-formats.md). ## Service principal and machine access For consumer and tenant callers, Mailbox uses the authenticated signed M7 principal projection. It must identify active service membership with a permitted service role (`member`, `user`, `admin`, or `root`). An outer token role or a request-body identity does not replace that membership. For machine callers, the receiving service authenticates its own ACL lookup and obtains the caller's permission for Mailbox. A machine's projection for its own list does not grant access to this receiver. Receiver ACL decisions may be reused for a bounded interval while the access token remains valid; applications must still handle denial after access changes. Missing receiver configuration or an unavailable ACL check can return `503`. Mailbox's current business-token profile uses Bearer transport. Sender-bound machine credentials are rejected with HTTP `401` and reason `sender_proof_required`; the current inbound path does not complete a DPoP or mTLS proof check for them. Do not treat a DPoP header or scheme as a supported substitute for this business Bearer profile. ## Workspace and project authority Without an organization selection, the caller is also the effective principal. Select an organization with the `Org` header or JSON `org_id` using the native organization UUID returned by `/orgs/list`. Selection requires the `orgs` scope and fresh verified direct Management membership for that caller and client. A cached organization list is only a selection aid. In an organization workspace, project access belongs to the organization's canonical `principal_id`. The token remains the real caller's token. The service intersects project capabilities with verified organization grants; an organization role alone is insufficient, and organization Member defaults grant no actions without appropriate capability selections. Active membership in a project and the exact action capability are required for sending, logs, and member management. A service role alone does not grant project access. Use `/projects/context` to read current effective capabilities. Do not send `owner`, `actor`, `owner_scope`, `organization_id`, or `client_id` as sending identity overrides. Logs likewise reject supplied identity overrides. The service derives identity from the token and workspace. ## Organization proof forwarding Organization discovery and selection can require a separate proof for the upstream SSO organization disclosure request. `/orgs/list` and `/orgs/refresh` accept JSON `orgs_dpop`. Organization-selected business requests accept the `Org-DPoP` header or JSON `orgs_dpop`; the header takes precedence. The proof is forwarded to the discovered SSO organization endpoint, normally `POST https://sso.user.m7.org/userinfo/orgs`. Generate it for that upstream request and the current access token, following [SSO organization disclosure](https://m7.org/docs/api/sso.user.m7.org/userinfo-orgs.md). A proof for the Mailbox business URL cannot be reused for a different target or method. Forwarded proof values must be strings of at most 8,192 bytes with no carriage returns, line feeds, or commas. If a nonce challenge returns `DPoP-Nonce`, make a fresh appropriate proof for the retry. This forwarding does not establish inbound DPoP support for Mailbox business tokens. Read [workspaces](https://m7.org/docs/api/api.mail.m7.org/workspaces.md) for selection and response fields, and [projects](https://m7.org/docs/api/api.mail.m7.org/projects.md) for resource access.