MessageHop

Home / Developers / Authentication

Scoped server credentials

A credential is an authorization boundary, not just an API key. It resolves the tenant hierarchy and permitted capability before a request body is trusted.

Header format

Authorization: Bearer mh_<environment>_<selector>_<secret>

Send the credential only over HTTPS. The selector supports safe lookup; the secret is verified against one-way material. A credential must be active and unexpired.

Canonical scope

Each credential resolves:

  • Organization, Brand, Project, and Registered App;
  • test or production environment;
  • allowed actions such as messages.send, messages.read, billing.read, or usage.read;
  • allowed channels such as SMS, WhatsApp, or email;
  • status, expiry, credential ID, and usage evidence.

Caller-supplied organization, role, project, app, or channel cannot broaden that scope. Protected v1 endpoints also require the Organization, Brand, Project, and Server App to remain active.

Storage rules

  • Store the secret in the customer backend's secret manager.
  • Inject it at runtime; do not commit it to source or a container image.
  • Redact Authorization headers in logs and traces.
  • Never send it through email, chat, analytics, query strings, crash reports, or support attachments.
  • Use different credentials for environments, apps, and independently revocable workloads.

Rotation without downtime

  1. Issue a replacement with the minimum required actions and channels.
  2. Deploy the replacement to the trusted backend.
  3. Verify successful calls and expected scope.
  4. Revoke the old credential.
  5. Confirm the old credential returns 401 unauthorized.

If exposure is suspected, revoke first and investigate second. A raw secret is shown once; MessageHop support cannot retrieve it.

Browser and mobile integrations

Do not put this credential in Flutter Web, browser JavaScript, iOS, Android, desktop apps, or downloadable configuration. Direct client operations require a separately designed restricted public identifier, attestation, origin or app binding, quota, and abuse controls. General MessageHop sending is server-to-server.