Skip to main content
Brudcast uses three credentials, one per integration surface. Each belongs to a single organization, so the credential alone decides which organization a request acts on.

​
Which credential works where

Every secret is shown once, when it’s created or regenerated. Brudcast stores only a hash of API keys and sending keys, so a lost key can’t be recovered. Regenerate it instead.

​
Platform API keys

A few rules follow from how keys are checked:
  • Bearer only works with the prefix. Brudcast reads Authorization: Bearer as an API key only when the value starts with bk_.
  • The organization comes from the key. You don’t need X-Organization-Id. If you send it and it names a different organization, the request fails with 403 and This API key cannot act on the requested organization.
  • Scopes narrow what the key can reach. A request to an endpoint the key has no scope for fails with 403 and code E_INSUFFICIENT_SCOPE. See API keys.
  • Some endpoints never accept a key. Key management, SMTP users, sending keys, billing, subscriptions, the wallet, invoices and notifications are dashboard-only. They answer 403 with This endpoint cannot be accessed with an API key. A leaked key can’t create more credentials or move money.
  • A key acts for the member who created it. If that member leaves the organization, their keys are revoked. If their account is suspended, the keys stop working.
Every authentication failure returns the same response, whatever the cause: an unknown, revoked or expired key, or a request from an IP address that isn’t on the key’s allowlist. This is deliberate, so a caller probing with stolen or guessed keys learns nothing.
If you get this with a key you believe is valid, check its status and IP allowlist in Developers > API Keys.

​
Sending keys

The email send API accepts only Authorization: Bearer <key>. It ignores X-API-Key. Two kinds of key work there: Prefer domain sending keys for applications that send from one domain. A leaked domain key can only send from that domain and can’t read anything. A key goes through these statuses on its way to the send API:
You can’t add the Send Messages permission to an existing API key. Create a new key with it. This is because the send API can only receive a key while its secret still exists, which is at creation or regeneration.
The Brudcast trial address has no sending keys and no SMTP credentials. Add and verify your own domain before you use the send API or SMTP. See Email overview.

​
SMTP users

An SMTP user is a username and password for the relay, tied to one sending domain.
  • Brudcast generates both. The username looks like an address on your domain, for example a1b2c3d4@mail.example.com. The password is 32 characters and shown once.
  • Authenticate with AUTH PLAIN or AUTH LOGIN. On ports 587, 2525 and 25, run STARTTLS first. Port 465 is TLS from the start.
  • The envelope sender (MAIL FROM) must be on the SMTP user’s domain.
  • You can regenerate the password or deactivate the user. After a regenerate, the old password can keep working for a few minutes.
See SMTP relay for connection settings and SMTP users for managing them.

​
Keeping credentials safe

  • Call Brudcast from your server. Never put a key in browser or mobile app code.
  • Use one key per application or environment, so you can revoke one without breaking the rest.
  • Give each API key only the scopes it needs.
  • Add an IP allowlist to keys used from fixed servers.
  • Set an expiry on keys that are only needed for a while.
  • If a key leaks, revoke it in the dashboard. It stops working on the next request.

API keys

Create keys, choose scopes and read request logs.

Errors

Every error shape and what to do about it.