> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uppzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Authentication

> Create, store, use, rotate, and revoke API keys for M2M integrations.

Uppzy M2M API uses API key authentication for server-to-server traffic.

Every M2M request must include your API key in the `X-API-Key` header:

```http theme={null}
X-API-Key: <YOUR_API_KEY>
```

## Prerequisites

Before you create an API key, confirm that:

* Your plan includes M2M API access
* Your account role is allowed to manage API keys
* You can access the API Access page in the dashboard

If the API Access page is not available, confirm plan and role first.

## Where to create the key

Create API keys from the dashboard:

* Product path: [API Access](/product/api-access)

Typical creation flow:

1. Open API Access
2. Enter a descriptive key name
3. Optionally set an expiry date
4. Create the key
5. Copy the plaintext key immediately
6. Store it in your secret manager or server configuration

Treat the plaintext key as sensitive. It should not be committed to source control, embedded in frontend code, or shared in chat messages.

## One-time copy pattern

In practice, API keys are commonly shown once at creation time.

Plan for that by:

* Storing the key immediately
* Tagging it with environment and owner information
* Recording when it should be rotated

Example naming convention:

* `prod-order-bot`
* `staging-crm-sync`
* `dev-support-prototype`

## Minimum request headers

For JSON requests:

```http theme={null}
X-API-Key: <YOUR_API_KEY>
Content-Type: application/json
```

For file uploads, send `X-API-Key` and let your HTTP client set the multipart boundary automatically.

## Connectivity check

Use a low-risk read request as your first connectivity test.

Example with `curl`:

```bash theme={null}
curl --request GET \
  --url "https://api.uppzy.com/api/v1/m2m/tenants/<TENANT_ID>/limits" \
  --header "X-API-Key: <YOUR_API_KEY>"
```

Use this check to confirm:

* The key is valid
* The key belongs to the expected tenant
* Your application can reach the API successfully

## JavaScript example

```js theme={null}
const response = await fetch(
  "https://api.uppzy.com/api/v1/m2m/tenants/<TENANT_ID>/limits",
  {
    headers: {
      "X-API-Key": process.env.UPPZY_API_KEY,
    },
  }
);

if (!response.ok) {
  throw new Error(`Authentication test failed: ${response.status}`);
}

const data = await response.json();
console.log(data);
```

## Python example

```python theme={null}
import os
import requests

resp = requests.get(
    "https://api.uppzy.com/api/v1/m2m/tenants/<TENANT_ID>/limits",
    headers={"X-API-Key": os.environ["UPPZY_API_KEY"]},
    timeout=30,
)

resp.raise_for_status()
print(resp.json())
```

## Key storage rules

Recommended storage locations:

* Secret manager
* CI/CD protected variables
* Server environment variables
* Encrypted deployment configuration

Do not store API keys in:

* Browser code
* Mobile app bundles
* Public repositories
* Shared screenshots or plain-text team notes

## Rotation strategy

Rotate keys on a schedule and after any incident that could expose them.

Recommended rotation sequence:

1. Create a new key
2. Deploy the new key to the target environment
3. Run a connectivity check and smoke test
4. Confirm production traffic uses the new key
5. Revoke the old key

Avoid deleting the old key before the new one is confirmed in production.

## Revocation strategy

Revoke a key immediately when:

* The owning integration is retired
* The key was shared incorrectly
* You suspect exposure
* Environment ownership changed

After revocation, verify that your application fails safely and that no background jobs continue retrying with the old key indefinitely.

## Common authentication failures

### `401 Unauthorized`

Typical causes:

* Missing `X-API-Key` header
* Wrong key value
* Expired or revoked key

### `403 Forbidden`

Typical causes:

* Plan does not include the requested capability
* The key is valid, but the operation is not permitted

### `404 Not Found`

Typical causes:

* Wrong tenant ID
* Wrong site ID
* Resource does not belong to the authenticated scope

### `429 Too Many Requests`

Typical causes:

* Burst traffic above allowed limits

Handle this with retry and backoff logic rather than immediate repeated retries.

## Production checklist

* Separate keys per environment
* Separate keys per integration when practical
* Server-side storage only
* Rotation schedule documented
* Connectivity test automated
* Revocation process documented
* Auth failures monitored in logs and alerts