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

# Authentication

> Authenticate UgaText API requests with your Client-ID and Client-Secret headers.

Every request must be sent over HTTPS with your `Client-ID` and `Client-Secret` in the request headers.

## Required headers

```http theme={null}
Client-ID: YOUR_CLIENT_ID
Client-Secret: YOUR_CLIENT_SECRET
Content-Type: application/json
```

| Header | Example | Description |
| - | - | - |
| `Client-ID` | `uga_9f8e7d6c5b4a` | Your public client identifier. |
| `Client-Secret` | `sk_live_98a7b6c5d4e3` | Your secret key. Keep it server-side. |
| `Content-Type` | `application/json` | Required for requests with a body. |

## Accepted header aliases

If your platform or proxy needs a different format, these alternatives are also accepted.

**X- prefixed headers**

For reverse proxies or platforms that require `X-*` header prefixes:

```http theme={null}
X-Client-ID: YOUR_CLIENT_ID
X-Client-Secret: YOUR_CLIENT_SECRET
```

**Bearer token**

A single header that combines both values with a colon:

```http theme={null}
Authorization: Bearer YOUR_CLIENT_ID:YOUR_CLIENT_SECRET
```

**X-API-Key**

```http theme={null}
X-API-Key: YOUR_CLIENT_ID:YOUR_CLIENT_SECRET
```

> [!WARNING]
>
> Do not send empty credentials or a placeholder such as `Authorization: Bearer :`. Missing, malformed, or revoked credentials return `401 INVALID_API_KEY`.

## Verify your credentials

Call `GET /auth/verify` to confirm your keys are valid and active.

```bash theme={null}
curl https://ugatext.com/api/v1/auth/verify \
  -H "Client-ID: YOUR_CLIENT_ID" \
  -H "Client-Secret: YOUR_CLIENT_SECRET"
```

## Manage API keys

| Action | Endpoint |
| - | - |
| Generate a key pair | `POST /auth/api-keys` |
| List keys | `GET /auth/api-keys` |
| Revoke a key | `POST /auth/api-keys/{id}/revoke` |

When generating a key you can set a `name`, a `mode` (`live` or `test`), `scopes`, and `allowed_ips`.

## IP whitelisting

Restrict a key so the API only accepts calls from your server's IPv4 or IPv6 addresses or CIDR ranges. Requests from any other IP return `403 IP_NOT_WHITELISTED`.

**Dashboard**

**1. Open API keys**

Sign in and open **Developer & API Keys** (`/dashboard/api-keys`).

**2. Create or edit a key**

Click **Create New API Key**, or **Configure** on an existing key.

**3. Add your IPs**

In **IP Whitelist (Optional)**, enter static IPs or CIDR ranges separated by commas, for example `203.0.113.42, 198.51.100.0/24`.

**4. Save**

Click **Save**. The restriction applies immediately.

**API**

Pass `allowed_ips` when you create a key:

```bash theme={null}
curl -X POST https://ugatext.com/api/v1/auth/api-keys \
  -H "Content-Type: application/json" \
  -H "Client-ID: YOUR_CLIENT_ID" \
  -H "Client-Secret: YOUR_CLIENT_SECRET" \
  -d '{
    "name": "Production Core Server",
    "mode": "live",
    "scopes": ["sms:send", "sms:read", "webhooks:manage"],
    "allowed_ips": ["203.0.113.42", "198.51.100.0/24"]
  }'
```

> [!TIP]
>
> Leave the list empty to allow any IP, for example on serverless platforms with dynamic egress IPs.

## Security practices

> **Store keys server-side**
>
> Keep credentials in server environment variables (`.env`). Never commit them to git.

> **HTTPS required**
>
> All requests must use TLS 1.2 or later. Plain HTTP requests are rejected.

> **Rotate keys instantly**
>
> Rotate compromised keys from your developer dashboard or through the API.

> **IP whitelisting**
>
> Optionally restrict API calls to designated static server IP addresses. See [IP whitelisting](#ip-whitelisting).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.