# Use the developer API and API keys

Create a server-side key, use the live contract and retry purchases without accidental duplicates.

2026-10-07 · SMS.Red

## Create and protect a key

Open Developers and the API keys area. Create a labelled key and save the displayed credential securely. Keys are account-scoped: calls use that account's wallet and orders in its store. They do not provide admin access or let you switch accounts through a request.

Use disable, delete or regenerate when available to revoke an old key. Regeneration invalidates the previous credential. Keep keys on your server, outside public browser code, screenshots and repositories.

## Read the live API contract

SMS.Red's base is `https://sms.red/api/v1/developer`. On a partner storefront use that store's own hostname. Authentication accepts `X-API-Key` or `Authorization: Bearer YOUR_API_KEY`. Use [interactive API documentation](/api/v1/developer/docs) and the current schema rather than guessing request fields.

Read balance and services before purchasing. Service listings distinguish `otp` and `rent`, country, stock and offered durations; durations use milliseconds. Purchase requests select the actual service identifier, country, duration and price ceiling. Optional provider or description fields depend on the documented operation.

## Handle purchases safely

Use a new `Idempotency-Key` for each intended purchase and the same key when retrying that purchase. Keys accept 8–128 ASCII letters, digits, underscores or hyphens. After a timeout, inspect the documented purchase-attempt lookup before deciding to start another order. Changing payload under the same key can produce a conflict.

```http
GET /api/v1/developer/balance
X-API-Key: YOUR_API_KEY
```

This example is a read request with a placeholder, not a real credential. Follow the live purchase examples for paid operations. Read owned orders and messages through their documented endpoints; cancellation remains subject to order eligibility and confirmation.

## Interpret errors and integrate messages

A 401 can mean missing, disabled, rotated or wrong-store credentials. A 404 can mean unavailable or unowned data. A 400 can reflect validation, funds or price conditions. For an unclear server result, preserve the purchase key and inspect the attempt instead of blindly creating a new key.

Use [Webhooks](/en/guides/webhooks) for incoming message events. Do not assume the API exposes every dashboard control; check the current contract for each operation.