Authentication

Every API request carries your secret key in the Authorization header:

curl https://api.msgbubbles.com/v1/messages \
  -H "Authorization: Bearer sk_live_…"

API keys

Keys look like sk_live_… (production) or sk_test_… (test mode) and are issued during onboarding.
The plaintext key is shown exactly once. We store only a hash, so a lost key cannot be recovered — it can only be replaced.
Keep keys server-side. Never embed them in mobile apps or browser code; anyone holding the key can send messages as your numbers.

Auth errors

Status	Meaning
`401 unauthorized`	The key is missing, malformed, unknown, or revoked.
`403 forbidden`	The key is valid but the account is not active.

Account scoping

A valid key is necessary but not sufficient. Everything you can reach — messages, conversations, attachments, webhooks — is scoped to your account, and the from_handle on a send must be a number assigned to you. Requests against another account’s resources return 404, never someone else’s data.

Your numbers

GET/v1/numbers

Lists the numbers your account can send from and what each can do — useful for rendering a from-number picker:

Response

{
  "data": [
    {
      "handle": "+18005551111",
      "channels": ["imessage", "sms", "whatsapp"],
      "label": "support line",
      "status": "online"
    }
  ],
  "request_id": "req_…"
}

Rate limits and the error envelope are described in Errors & limits.