Generating an API Key

Step 1: Navigate to API Integration

1. Log in to your NestSMS Dashboard
2. In the left sidebar, go to API Integration → API Token
3. Click the Add Token button

Step 2: Configure Your Key

Enter a descriptive name for your API key to help you identify its purpose later.

Optionally, you can configure:

• IP Whitelist: Restrict the key to specific IP addresses
• Permissions: Limit what the key can do (send SMS, check balance, etc.)
• Expiry Date: Set an expiration date for the key

Step 3: Copy Your API Key

Once generated, your API key will be displayed. Copy it immediately — it will only be shown once for security reasons.

nsms_live_abc123xyz789def456ghi012jkl345mno678

Using Your API Key

Include your API key in every request using one of these methods:

Method 1: X-API-Key Header (Recommended)

curl -X POST https://api.nestsms.com/api/v1/sms/send \
  -H "X-API-Key: nsms_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "9840123456", "message": "Test SMS"}'

Method 2: Authorization Bearer Token

curl -X POST https://api.nestsms.com/api/v1/sms/send \
  -H "Authorization: Bearer nsms_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "9840123456", "message": "Test SMS"}'

Key Prefixes

NestSMS API keys use prefixes to indicate their environment:

Storing API Keys Securely

Environment Variables

Never hardcode API keys in your source code. Use environment variables instead:

# .env
NESTSMS_API_KEY=nsms_live_your_api_key_here

In Your Application

Access the key from environment variables:

// Node.js / Next.js
const apiKey = process.env.NESTSMS_API_KEY;

// Python
import os
api_key = os.getenv('NESTSMS_API_KEY')

// PHP
$apiKey = $_ENV['NESTSMS_API_KEY'];

Managing API Keys

Viewing Your Keys

Go to API Integration → API Token to see all your active keys. You'll see:

• Key name
• Partial key (last 8 characters)
• Creation date
• Last used date
• Permissions

Revoking Keys

To revoke a compromised or unused key:

1. Go to API Integration → API Token
2. Find the key you want to revoke
3. Click the Delete or Revoke button
4. Confirm the action

Revoked keys are immediately invalidated and cannot be recovered.

Rotating Keys

For security best practices, rotate your API keys regularly:

1. Generate a new API key
2. Update your application with the new key
3. Test thoroughly to ensure everything works
4. Once verified, revoke the old key

IP Whitelisting

Enhance security by restricting which IP addresses can use your API key:

1. Edit your API key settings
2. Add allowed IP addresses (comma-separated)
3. Save changes

Example: 203.0.113.1, 203.0.113.2

Permissions

You can create keys with limited permissions for specific use cases:

Troubleshooting

Invalid API Key

{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Solutions:

• Verify the key is correct (check for typos or extra spaces)
• Ensure the key hasn't been revoked
• Check that you're using the correct environment (test vs live)

API Key Expired

{
  "success": false,
  "error": "API key has expired",
  "code": "API_KEY_EXPIRED"
}

Solutions:

• Generate a new API key
• Remove expiry dates from keys that should remain active

IP Restricted

{
  "success": false,
  "error": "Request from non-whitelisted IP",
  "code": "IP_RESTRICTED"
}

Solutions:

• Add your current IP to the whitelist
• Remove IP restrictions if not needed
• Use a VPN or proxy from an allowed IP

Best Practices

1. Use Descriptive Names: Name keys based on their purpose (e.g., "Production API", "Staging Server")
2. Principle of Least Privilege: Grant only necessary permissions
3. Regular Rotation: Rotate keys every 90 days
4. Monitor Usage: Check last used dates regularly
5. Separate Environments: Use different keys for dev, staging, and production
6. Set Expiry Dates: For temporary integrations or testing
7. Enable IP Whitelisting: For server-to-server communications

Next Steps

• View complete API Reference
• Send your first SMS
• Integrate with frameworks
• Setup white-label platform