Authentication

Requests are authenticated with the api_key in the JSON body. Key management and security.

Every request is a POST request and must include the api_key field in its JSON body. There is no Authorization header and no Bearer token. The Content-Type: application/json header is required on every request.

Validate a key

The /auth/check endpoint returns, in a single request, whether your key is valid, your account status, and which permissions are defined.

curl -X POST https://api.turkeysms.com.tr/auth/check \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_API_KEY"}'

{
  "result": true,
  "result_code": "TS-1000",
  "key_details": {
    "status": "Active",
    "permissions": {
      "send_single_sms":  true,
      "send_otp":         true,
      "send_bulk_sms":    true,
      "check_balance":    true,
      "check_sms_status": true
    }
  },
  "account_summary": {
    "account_status": "Active",
    "balance": { "main": 1500, "international": 250 }
  }
}

Permission matrix

Each key has its own set of permissions (e.g. send_single_sms, send_otp, send_bulk_sms, check_balance). If a key lacks the permission for an operation, the request is rejected with TS-1065. Scoping permissions with a separate key per environment is recommended.

Key security

• Keys are account-bound and can be rotated at any time.
• Revocation is immediate — a revoked key is rejected at once.
• An IP allowlist can be defined per key; only requests from listed IPs are accepted.