Skip to main content

​
API Authentication

Vellosim uses API key authentication to secure all API requests. Your API key identifies your account and authorizes access to the API endpoints.

​
Getting Your API Key

Follow these steps to generate your API key:
1

Sign Up / Login

Create a merchant account at vellosim.com and log in to your dashboard
2

Navigate to Developer Section

Go to the Developer section in your dashboard sidebar
3

Generate API Key

Click the “Generate API Key” button
4

Save Your Key

Copy and securely store your API key - it will only be shown once!
Generate API Key in Developer Dashboard
Keep your API key secure! Never share it publicly, commit it to version control, or expose it in client-side code.

​
Required Information

When generating your API key, you’ll need to provide:
  • Company Name - Your business or organization name
  • Website URL - Your website (must be accessible)
  • Whitelisted IPs - IP addresses allowed to use this API key (1-10 addresses)
  • Webhook URL (Optional) - URL to receive event notifications

​
Using Your API Key

Include your API key in the X-API-Key header of every request using the API Key format: 
X-API-Key: YOUR_API_KEY

​
Example Requests

curl -X GET "https://api.vellosim.com/api/esim/regions" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Environment Variables

Store your API key in environment variables to keep it secure: 
VELLOSIM_API_KEY=your_api_key_here
VELLOSIM_BASE_URL=https://api.vellosim.com

​
Authentication Errors

If authentication fails, you’ll receive an error response: 
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "statusCode": 401
}
Common authentication errors:
Status CodeErrorDescription
401UnauthorizedMissing or invalid API key
403ForbiddenValid key but insufficient permissions
429Too Many RequestsRate limit exceeded

​
Best Practices

Never hardcode your API key in your source code. Always use environment variables or secure configuration management.
Periodically rotate your API keys to maintain security. You can generate new keys from your dashboard.
Use separate API keys for development, staging, and production environments.
Regularly check your API usage in the dashboard to detect any unusual activity.
Only use your API key in server-side applications. Never expose it in client-side JavaScript, mobile apps, or public repositories.

​
Rate Limiting

To ensure fair usage and system stability, API requests are rate-limited:
  • Standard Plan: 100 requests per minute
  • Premium Plan: 500 requests per minute
  • Enterprise Plan: Custom limits
Rate limit information is included in response headers: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699564800
If you need higher rate limits, contact our sales team at [email protected] to discuss enterprise options.

​
Next Steps

Making Requests

Learn how to structure your API requests

Error Handling

Handle API errors gracefully