Authentication

The current SMS v2 contract

This page describes authentication for the SMS API under /api/sms/v2/. It does not define the contract of future products in advance. For the previous API, see SMS v1 and migration.

SMS v2 accepts only an organization API key issued in BEFIANA Cloud. Send the complete value, including its bf_sms_ prefix, in this header:

Authorization: Bearer bf_sms_<key_id>.<secret>

<key_id> and <secret> stand for the parts of the key supplied at creation. A legacy key, even when attached to an organization, a JWT or a key sent without Bearer cannot authenticate v2 requests. A person’s Cloud login is separate from your integration’s authentication.

For requests with a JSON body, use Content-Type: application/json. You can explicitly request a JSON response with Accept: application/json. Keep the key in your server application and send requests over HTTPS.

One key identifies one organization

The API determines the organization from the key. Do not send X-Organization: this header is rejected with 400 invalid_organization_header. To work with another organization, use a key created within that organization.

Resource access is restricted to that organization. A message or batch identifier belonging to another organization returns 404 not_found. Knowing its identifier does not grant access to its content.

Capabilities authorize operations

A valid key must also have the capability required by the requested operation:

Scroll horizontally if needed. Keyboard: Tab, then the left and right arrow keys.

Capability	SMS v2 operations
sms.send	Create an immediate message with POST /messages/.
sms.schedule	Create a message with send_at, or a batch with POST /message-batches/.
delivery.read	Read a message, a batch or the messages in a batch.
balance.read	Read credits with GET /balance/.
contacts.manage	Create or update a contact with POST /contacts/.

These paths are relative to /api/sms/v2/. A sending integration that needs to check an uncertain outcome also needs delivery.read. Permission to administer keys in Cloud is separate from the capabilities granted to a key.

Diagnose access errors

Scroll horizontally if needed. Keyboard: Tab, then the left and right arrow keys.

Code	Check
401 invalid_api_key	Check the Bearer syntax, complete value and active state of the key. A revoked key can no longer authenticate a new request.
403 insufficient_permissions	Use a key with the required capability.
403 sms_unavailable	Check in Cloud that the organization and SMS are active; sending also requires a valid SMS activation.

Authentication does not replace other checks: available credits, schedule time and sender name authorization. See the SMS error catalogue.

To create, store and rotate credentials, follow the API keys guide. Protection against duplicate submissions uses a different header, Idempotency-Key, described in Idempotency and retries.