---
title: "How do I authenticate with the Enfonica API?"
url: "https://enfonica.com/help/developers/api-authentication"
summary: "Create a service account in your project, give it a role, and download its JSON key. Then point the Enfonica client libraries at the key with ENFONICA_APPLICATION_CREDENTIALS. For tools that can send only a fixed Authorization header, our support team can provision a bearer token linked to a service account."
type: explainer
audience: everyone
products: ["Cloud SMS", "Cloud Voice", "Phone Numbers"]
who_can_do_this: "A project Owner or Editor creates service accounts"
---

# How do I authenticate with the Enfonica API?

**Short answer:** Create a service account in your project, give it a role, and download its JSON key. Then point the Enfonica client libraries at the key with ENFONICA_APPLICATION_CREDENTIALS. For tools that can send only a fixed Authorization header, our support team can provision a bearer token linked to a service account.

**Applies to:** Cloud SMS, Cloud Voice, Phone Numbers  
**Who can do this:** A project Owner or Editor creates service accounts

## 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](https://console.enfonica.com/), 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.

> **Warning:** You can't download the key file again, and anyone who has it can act as the service account. Store it as you would a password, and keep it out of your source code.

## 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](https://enfonica.com/help/console/users-and-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](https://enfonica.com/docs/libraries/overview/). 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](https://enfonica.com/help/sender-ids/register-alphanumeric-sender-id).

## What do common errors mean?

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

| Error | What it usually means | What to do |
| --- | --- | --- |
| `403` Forbidden | The credential isn't valid for this project, or the service account's role doesn't allow this action. | Check that the project in the URL is the one that the key or token belongs to, and that the role includes the product. |
| `Jwt issuer is not configured` | The request carries a token that Enfonica didn't issue, such as one built by hand from the key file. | Use a client library with the key file, or ask us for a bearer token. |
| `400` Bad Request when sending to one number | That person might have replied STOP. Unsubscribed numbers are blocked by default. | Check **Cloud SMS > Unsubscribers** in the Console. |

## 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](https://enfonica.com/docs/platform/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.

## Related

- [Add users to the Console and choose their access](https://enfonica.com/help/console/users-and-access.md)
- [Download your call and SMS records](https://enfonica.com/help/developers/call-and-sms-records.md)
- [Authentication (docs)](https://enfonica.com/docs/authentication/)
- [Service accounts (docs)](https://enfonica.com/docs/projects/service-accounts/)
- [Client libraries (docs)](https://enfonica.com/docs/libraries/overview/)
- [Request signing (docs)](https://enfonica.com/docs/platform/request-signing/)

---

Web version: https://enfonica.com/help/developers/api-authentication