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 <access-token> 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 with the grant appropriate to your application. Human applications can use authorization or device authorization. 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:

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.

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. 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 for selection and response fields, and projects for resource access.