# Authentication
URL: /docs/getting-started/authentication

> Secure your API requests with X-Api-Key or Bearer tokens, enforce granular scopes, and protect operations with idempotency.

All requests to the SMS Pro Developer Platform must be authenticated over HTTPS. Unauthenticated calls or requests with invalid keys will be rejected with an HTTP `401 Unauthorized` or `403 Forbidden` response.

---

## Authentication Schemes [#authentication-schemes]

SMS Pro supports two standard methods for supplying your API credentials:

### 1. `X-Api-Key` Header (Recommended) [#1-x-api-key-header-recommended]
Pass your secret key in the custom `X-Api-Key` header:

```http
POST /api/v1/public/sms/send HTTP/1.1
Host: api.smspro.com
X-Api-Key: sk_live_948f293048a1b2c3d4e5f60718a2b3c4
Content-Type: application/json
```

### 2. `Authorization: Bearer` Header [#2-authorization-bearer-header]
Alternatively, use the RFC 6750 standard `Bearer` authorization scheme:

```http
POST /api/v1/public/sms/send HTTP/1.1
Host: api.smspro.com
Authorization: Bearer sk_live_948f293048a1b2c3d4e5f60718a2b3c4
Content-Type: application/json
```

---

## Anatomy of an API Key [#anatomy-of-an-api-key]

SMS Pro uses distinct, human-readable key prefixes to prevent accidental environment mismatches:

| Prefix | Behavior |
| :--- | :--- |
| `sk_test_` | Simulated delivery on `https://api.smspro.com`. No wallet charge. |
| `sk_live_` | Carrier delivery on the same API. Uses wallet credit. |

<Callout type="info" title="Same host">
Test keys and live keys are both sent to `https://api.smspro.com`. The key prefix selects simulated delivery or carrier delivery.
</Callout>

---

## Essential Request Headers [#essential-request-headers]

When constructing API calls, include the following headers:

| Header | Required? | Format / Value | Description |
| :--- | :--- | :--- | :--- |
| `X-Api-Key` | Required* | `sk_live_...` or `sk_test_...` | Secret API key (*or use `Authorization: Bearer`). |
| `Content-Type` | Required for `POST`/`PUT` | `application/json` | All request bodies must be JSON encoded. |
| `Idempotency-Key` | Recommended for `POST` | UUID v4 (e.g. `9b1deb4d-...`) | Unique request ID with a 24-hour cache TTL preventing duplicate dispatches on network retries. |

---

## Understanding Idempotency Keys [#understanding-idempotency-keys]

Network blips and client timeouts can occur during mobile or server-to-server operations. If your application sends a payment receipt SMS and times out after 5 seconds, retrying the call blindly could result in the customer receiving duplicate text messages and your balance being deducted twice.

To prevent this, supply a unique `Idempotency-Key` on every mutating request:

```ts
const idempotencyKey = crypto.randomUUID();

const res = await fetch('https://api.smspro.com/api/v1/public/sms/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': process.env.SMSPRO_API_KEY!,
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify({
    to: '+233241234567',
    senderId: 'SMSPRO',
    message: 'Your order #89201 has been dispatched.',
  }),
});
```

- If SMS Pro receives a request with an `Idempotency-Key` that was already processed within the past 24 hours, it **immediately returns the cached initial response** without re-queueing the SMS or billing your wallet again.
- Idempotency keys are cached per-organization, so keys from different accounts will never collide.

---

## Scope Verification & Principle of Least Privilege [#scope-verification--principle-of-least-privilege]

Every API key has a specific set of granted permissions. If your key attempts to access an endpoint outside its configured scopes, the gateway returns HTTP `403 Forbidden`:

```json
{
  "type": "https://docs.smspro.com/errors/forbidden-scope",
  "title": "Forbidden Scope",
  "status": 403,
  "detail": "API key lacks the required 'mfa:write' scope to access this resource.",
  "code": "AUTH_FORBIDDEN_SCOPE",
  "requestId": "req-9b1deb4d",
  "timestamp": "2026-11-18T08:45:00Z"
}
```

To resolve this error, visit **Developer > API Keys** in the console and either edit the key's assigned scopes or generate a dedicated key with the required permissions.

---

## Zero-Downtime Key Rotation [#zero-downtime-key-rotation]

When cycling secrets or replacing a potentially compromised key, execute a zero-downtime rotation:

<Steps>
<Step>
**Generate a New Key**

In the SMS Pro Console, generate a new scoped key with identical permissions and environments.
</Step>

<Step>
**Update Application Secrets**

Deploy the new key (`SMSPRO_API_KEY`) to your production staging and worker fleets.
</Step>

<Step>
**Verify Traffic in API Logs**

Navigate to **Developer > API Logs** and verify that requests are arriving successfully with the new key prefix.
</Step>

<Step>
**Revoke the Old Key**

Click **Revoke** on the legacy key in the console to permanently disable it.
</Step>
</Steps>

---

## Common Authentication Errors [#common-authentication-errors]

| Status | Error Code | Root Cause & Resolution |
| :--- | :--- | :--- |
| `401` | `UNAUTHORIZED` | The key is missing, unknown, or the caller address is not on the IP whitelist. |
| `403` | `FORBIDDEN_SCOPE` | The key does not include the scope for this endpoint. |
| `422` | `API_KEY_ALLOCATION_EXCEEDED` | The key has used its SMS allocation. |

---

## Next Step [#next-step]

Learn how test keys and live keys share one API in [Environments](/docs/getting-started/environments).