How do I authenticate with the Enfonica API?

What is a service account?

A service account is a login for an app instead of a person. It's how Enfonica API authentication works. A service account belongs to one project, has a role in the same way a user does, and is identified by an email address, such as my-service-account@my-project.iam.enfonica.com. Your app proves that it's the service account with a key file that you download from the Console.

Give each app its own service account instead of a person's login. Then the app keeps working when staff change, and it can have exactly the access it needs and no more.

How do I create a service account and key?

A project Owner or Editor can create a service account in the Console. To create one:

1. In the Enfonica Console, open the project, and go to Settings > Service accounts.
2. Select Create service account.
3. Enter a Service account ID of 6 to 30 lowercase letters, digits, and hyphens, for example sms-sender. You can also enter a description.
4. Select a Role, and then select Create.
5. Open the new service account. Under Keys, select Add key, and then select Create and download key. A JSON key file downloads.

Which role should the service account have?

Give it the least access that your app needs. Service accounts use the same roles as people, including Custom roles, which grant access one product at a time. For example, an app that only sends SMS needs Messaging with Editor selected, and nothing else.

For each role, see Add users to the Console and choose their access.

How do I use the key with the client libraries?

Set the ENFONICA_APPLICATION_CREDENTIALS environment variable to the path of the key file. This is the recommended way to authenticate. Enfonica's client libraries read the key from that path, and authenticate as the service account on every request.

export ENFONICA_APPLICATION_CREDENTIALS=/path/to/key.json

To learn how to install each library and send your first request, see the client library docs. The docs are agent-ready, so your AI coding assistant can work from them too.

Can I call the REST API from Postman or a no-code tool?

Yes, with a bearer token from our support team. A key file is still the recommended way to authenticate. But you can't paste a key file into an Authorization header, which is why using one directly in tools such as Postman or Power Automate fails.

To get a token, contact us with the project and the service account that the token should belong to. We'll provision a token and send it to you securely.

Send the token in the Authorization header of each request. Write Bearer exactly as shown, because it's case sensitive.

Authorization: Bearer your-token-here

A token works only for the project that its service account belongs to, so each project needs its own token. A token has the same access as its service account. Give that service account the smallest role that works, and store the token as you would a password.

What does a request look like?

This request sends an SMS with the Cloud SMS REST API. Replace the token, the project, and the numbers with your own.

curl -X POST \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "+61491570156", "from": "+61491570157", "body": "This is a test from the Cloud SMS API"}' \
  https://messaging.api.enfonica.com/v1/projects/my-project/messages

The from value is a number in your project, or a sender ID that you've registered. To send from a business name in Australia, see Register an alphanumeric sender ID for SMS in Australia.

What do common errors mean?

Most authentication errors mean that the request carries the wrong kind of credential, or one for a different project.

How do I check that webhooks really come from Enfonica?

Verify the signature on each request. Enfonica signs every webhook with HMAC-SHA256, and sends the result in the X-Enfonica-Signature header. The signature is calculated from the full URL, the X-Enfonica-Event header, and the raw body.

Your project's signing key is in the Console under Settings > General, in Project signing key. The Console shows the key encoded, so Base64-decode it before you use it.

Webhooks don't support basic authentication, so the signature is how you know that a request is genuine. For the algorithm, a test vector, and code you can copy, see Request signing.

How do I replace or revoke a key?

To replace a key:

1. Open the service account in Settings > Service accounts, and add a new key.
2. Deploy the new key file to your app, and check that it works.
3. Under Keys, select the menu beside the old key, and then select Delete key.

Deleting a service account deletes all of its keys. If a key or bearer token might have been exposed, delete the key right away. Then contact us about any bearer token linked to that service account.