API keys

Create an SMS key in Cloud

The keys described here apply to SMS v2. Creation and revocation take place in BEFIANA Cloud; the public SMS v2 routes do not provide key administration operations.

1. Sign in to SMS API integration in Cloud and select your integration’s organization.
2. Under Clés API de l’organisation (organization API keys), complete Nom de la clé (key name). Choose a name that identifies the responsible application or integration.
3. Select at least one capability, limiting permissions to the operations you need. See the capability table.
4. Click Créer une clé API (create an API key) and copy the complete value into your secrets manager.
5. Close the window after saving the key. The secret will not be displayed again.

Your Cloud account must have access to the organization and permission to manage its SMS API keys. If management controls are unavailable, ask its administrator for access. Creating a key does not automatically activate SMS or add credits.

The copied value starts with bf_sms_. For SMS v2, add Bearer before this value in Authorization, as described in Authentication. Cloud instructions about the v1 header do not change this v2 syntax.

Store the secret

The complete secret is available only at creation. The key list displays information including names, identifiers, capabilities and state, but cannot retrieve the secret. If you lose it, create another key and revoke the one you can no longer use.

Store the value in a secrets manager or protected server configuration. Do not embed it in browser code, a distributed application, a repository or a URL. Redact the Authorization header in logs and support exchanges. See also Security.

Prefer one key per integration and a separate key for each organization. This lets you revoke an access without replacing credentials in every application. A key’s usage information helps track its activity; it is not a count of SMS messages sent or billed.

Rotate a key

1. Create a new key in the same organization, with the required capabilities.
2. Update the integration’s secret and verify an authorized read operation. For example, reading the balance requires balance.read.
3. Check that your application’s instances use the new key, then revoke the previous one in Cloud.

Rotating an API key does not reset idempotency: to retry a message or batch already submitted, keep the same Idempotency-Key, path and body. Its scope depends on the organization, not on the API key used. Do not send an additional SMS to test rotation for an existing operation.

To change the granted capabilities, create a key with the desired permissions, then replace and revoke the previous one. There is no public SMS v2 operation for changing these permissions.

Revoke access

In the Cloud list, use the revocation action for the relevant key and confirm. Revocation prevents new authentication with that key and does not reveal its secret. It does not cancel messages already accepted or scheduled.

Revoke keys that are no longer needed or have been compromised. The departure of a key’s creator does not itself revoke an organization key: include keys in your access removal procedure.

Limits to understand

A valid key does not bypass activation, capability, credit or sender name checks. The SMS v2 contract does not provide automatic renewal, a configurable expiration period or IP address restrictions for these keys. Creating an additional key does not increase the permitted batch size or available throughput. See SMS limits.