Authentication

The Agile Telecom SMS API accepts two authentication methods over HTTPS. API Key is recommended for new integrations.

API Key (Recommended)

Send your API key in the X-Api-Key header on every request.

Getting Your API Key

1. Sign in to the wholesale portal.
2. Open Settings → API Keys.
3. Generate a new key or copy your existing one.
4. Store it as an environment variable on your backend — never commit it to source control.

Using an API Key

cURL

curl -X POST https://wholesale.agiletelecom.com/services/sms/send \
  -H "X-Api-Key: $AGILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "destinations": ["+393351234567"],
        "sender": "Agile",
        "body": "Hello from Agile Telecom!"
      }
    ]
  }'

Python

import os
import requests

headers = {
    "X-Api-Key": os.environ["AGILE_API_KEY"],
    "Content-Type": "application/json",
}

payload = {
    "messages": [
        {
            "destinations": ["+393351234567"],
            "sender": "Agile",
            "body": "Hello from Agile Telecom!",
        }
    ]
}

response = requests.post(
    "https://wholesale.agiletelecom.com/services/sms/send",
    json=payload,
    headers=headers,
    timeout=10,
)
print(response.json())

Node.js

const axios = require('axios');

const config = {
  headers: {
    'X-Api-Key': process.env.AGILE_API_KEY,
    'Content-Type': 'application/json',
  },
};

const data = {
  messages: [
    {
      destinations: ['+393351234567'],
      sender: 'Agile',
      body: 'Hello from Agile Telecom!',
    },
  ],
};

axios
  .post('https://wholesale.agiletelecom.com/services/sms/send', data, config)
  .then((res) => console.log(res.data))
  .catch((err) => console.error(err.response?.data));

Basic Authentication

If API keys are not suitable for your environment, use Base64-encoded credentials.

Generating Basic Auth Credentials

On macOS/Linux:

echo -n "username:password" | base64

On Windows (PowerShell):

[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("username:password"))

Using Basic Auth

cURL

curl -X POST https://wholesale.agiletelecom.com/services/sms/send \
  -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "destinations": ["+393351234567"],
        "sender": "Agile",
        "body": "Hello from Agile Telecom!"
      }
    ]
  }'

Python

import requests
from requests.auth import HTTPBasicAuth

response = requests.post(
    "https://wholesale.agiletelecom.com/services/sms/send",
    json={
        "messages": [
            {
                "destinations": ["+393351234567"],
                "sender": "Agile",
                "body": "Hello from Agile Telecom!",
            }
        ]
    },
    auth=HTTPBasicAuth("username", "password"),
    timeout=10,
)

print(response.json())

Node.js

const axios = require('axios');

const auth = { username: 'username', password: 'password' };

const data = {
  messages: [
    {
      destinations: ['+393351234567'],
      sender: 'Agile',
      body: 'Hello from Agile Telecom!',
    },
  ],
};

axios
  .post('https://wholesale.agiletelecom.com/services/sms/send', data, { auth })
  .then((res) => console.log(res.data))
  .catch((err) => console.error(err.response?.data));

IP Whitelisting

Add an extra layer of security by restricting API access to specific source IPs. Optional but strongly recommended for production.

1. Open Settings → Security on the wholesale portal.
2. Enable IP whitelist.
3. Add your server's public IP address(es).
4. Save.

Requests from non-whitelisted IPs return 403 Forbidden.

Error Codes

Code	Meaning	Action
401	Invalid credentials	Re-check API key or Basic Auth credentials
403	Unauthorized IP	Verify the calling IP is whitelisted (if enabled)
429	Rate limit exceeded	Apply exponential back-off, see Best Practices

Security Best Practices

1. Never expose API keys in client-side code — Use them only on your backend.
2. Store keys in environment variables — Do not hardcode them.
3. Rotate keys regularly — Every 90 days in high-security environments.
4. HTTPS only — All requests must be over TLS; from January 15th, 2026 non-TLS connections are rejected.
5. Use IP whitelisting when your backend has a stable public IP.
6. Monitor usage — Watch for unexpected traffic spikes in the wholesale portal.

Need help? Contact support at help@agiletelecom.com or open the wholesale portal.