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:

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:

Auth block

{
  "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:

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

For send-sms you add a message field; see 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.

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):

{
  "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

{
  "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

Code samples

cURL

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, full patterns on the test-mode page.

Related

• API overview
• Send SMS (send-sms)
• Get balance (get-balance)
• Error code table

Last updated: 2026-04-29 · Türkçe