---
title: "iletiMerkezi API Authentication"
description: "Authenticate to the iletiMerkezi API with an API Key + Hash. Panel prerequisite, request format, 401 errors, and language samples."
slug: /en/docs/api/authentication
locale: en
audience: developer
last_updated: 2026-04-29
endpoint:
  method: POST
  path: /v1/* (same pattern across all endpoints)
  base_url: https://api.iletimerkezi.com
auth: api-key-and-hash
related: [overview, send-sms, error-codes]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/authentication
  en: https://www.iletimerkezi.com/en/docs/api/authentication
  toplusmsapi: https://toplusmsapi.com/giris/genel-bilgiler
  a2psmsapi: https://a2psmsapi.com/en/giris/genel-bilgiler
---

# iletiMerkezi API Authentication

The iletiMerkezi REST API authenticates requests with an **API Key + Hash** pair. Both values are issued by the panel; you do not compute them at runtime. They travel inside the JSON body under `request.authentication`, not as a separate HTTP header.

## Prerequisite: enable API access in the panel

> Before your first request, the **Allow API access** toggle must be on in your iletiMerkezi panel.
>
> Location: `panel.iletimerkezi.com` → **Settings → Security → Access Permissions**
>
> If it is off, every request returns `401 — Authentication failed`. This does not mean your key is wrong; it means the toggle is closed. More than 90% of developers hit this on their first attempt.

## Where to find your credentials

1. Open `panel.iletimerkezi.com` → **Settings → Security → API Access**.
2. Copy the **API Key** and **API Hash** from the panel. Both are hex strings.
3. Store them as environment variables in your application:

```bash
ILETIMERKEZI_API_KEY=...
ILETIMERKEZI_API_HASH=...
```

> **Do not generate the hash yourself.** The iletiMerkezi panel issues a precomputed hash; SDKs and direct HTTP clients pass it through unchanged. There is no MD5 / SHA / HMAC step in your code.

## Request format

Every endpoint is called with `POST` and shares the same body envelope:

| Field | Value |
|---|---|
| Method | `POST` |
| URL | `https://api.iletimerkezi.com/v1/{endpoint}/json` |
| Content-Type | `application/json` |
| Auth field | `request.authentication.{key, hash}` |

### Auth block

```json
{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    }
  }
}
```

Each endpoint adds its own fields next to this block. For `get-balance` no extra fields are needed:

```json
{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    }
  }
}
```

For `send-sms` you add a `message` field; see [send-sms.md](./send-sms.md) for details.

## Verifying your credentials

The fastest way to confirm your keys work is to call `get-balance`. It has no side effects, does not consume credits, and can be retried safely.

```bash
curl -X POST 'https://api.iletimerkezi.com/v1/get-balance/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "API_KEY",
        "hash": "API_HASH"
      }
    }
  }'
```

Successful response (HTTP 200):

```json
{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "balance": {
      "amount": 10.584,
      "sms": 69
    }
  }
}
```

Note: status messages are returned in Turkish. `İşlem başarılı` means "Request successful". If you receive this body, authentication is working and you can call other endpoints.

## Error responses

### 401 — Authentication failed

```json
{
  "response": {
    "status": {
      "code": 401,
      "message": "Üyelik bilgileri hatalı"
    }
  }
}
```

The Turkish message reads "Membership information is invalid".

**Most common causes (in order):**

1. **The "Allow API access" toggle is off in the panel.** This is the leading cause of first-attempt 401 errors. The message is generic, so it is easy to misread as a credential problem.
2. **API Key or Hash copied incorrectly.** Re-check the values in your environment variables against the panel; pay attention to leading and trailing whitespace.
3. **IP restriction is enabled but the request's source IP is not whitelisted.** If you have configured an API IP whitelist under **Settings → Security → Static IP**, requests from any other IP return 401. Add your server's outbound IP to the list, or disable the restriction.
4. **Key has been rotated or disabled.** Generate a new key in the panel and update your application.

Full error code table: [error-codes.md](./error-codes.md)

## Code samples

### cURL

```bash
curl -X POST 'https://api.iletimerkezi.com/v1/get-balance/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      }
    }
  }'
```


## Common pitfalls

- **Panel toggle 401.** The number-one first-time failure. The message says "Authentication failed" but the real cause is that API access is disabled. Check the panel before rotating keys for hours.
- **Do not compute the hash yourself.** Older guides on the internet may show MD5 or SHA pipelines. iletiMerkezi issues the hash from the panel; computing it client-side will produce a wrong value and a 401.
- **Never commit credentials.** API Key and Hash carry full account permissions. Store them in `.env`, Vault, AWS Secrets Manager, or your CI's secret store, never in source control.
- **Do not test by sending SMS.** Use `get-balance` to verify auth. `send-sms` consumes credits on every successful call and delivers a real message to the destination number.
- **There is no separate sandbox key.** The same key works for both development and production. New accounts receive **100 free SMS credits** for testing and evaluation, which covers the first integration without extra cost. Standard pattern: a "TEST" prefix in the message body and your own verified test number as the recipient.


## Related

- [API overview](./overview.md)
- [Send SMS (send-sms)](./send-sms.md)
- [Get balance (get-balance)](./get-balance.md)
- [Error code table](./error-codes.md)