Authentication
The echowin API uses API keys to authenticate requests. You can view and manage your API keys in the API Keys page of your portal.
How it works
Authentication to the API is performed via API keys. Include your API key in the X-API-Key header for all API requests:
X-API-Key: your-api-key-hereKeep your API key secure!
Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Making authenticated requests
Here's how to make an authenticated request using different programming languages:
cURL
curl https://echo.win/api/v1/contacts \
-H "X-API-Key: your-api-key-here"JavaScript
const response = await fetch('https://echo.win/api/v1/contacts', {
headers: {
'X-API-Key': 'your-api-key-here'
}
});Python
import requests
response = requests.get(
'https://echo.win/api/v1/contacts',
headers={'X-API-Key': 'your-api-key-here'}
)API Key Management
Creating API Keys
API keys can be created from your portal settings. Each key is unique and tied to your team account.
Security Best Practices
- Store API keys in environment variables
- Never commit API keys to version control
- Rotate keys regularly
- Use different keys for different environments
Key Permissions
API keys have full access to your team's resources. They can perform any action that you can do in the portal.
Authentication Errors
The API will return specific error responses for authentication issues:
/api/v1/contactsExample of authentication error responses
Responses
{
"error": "Missing X-API-Key header"
}{
"error": "Invalid API key"
}Rate Limiting
API requests are rate limited per team to ensure fair usage and system stability. Rate limits vary by operation type:
| Operation Type | Limit | Window |
|---|---|---|
| Standard (GET requests) | 100 requests | per minute |
| Search (semantic search, filtered queries) | 30 requests | per minute |
| Write (POST, PUT, DELETE) | 60 requests | per minute |
| Bulk (bulk create/update operations) | 10 requests | per minute |
| Resource-specific (e.g., webpage refresh) | 1 request | per day per resource |
Rate Limit Headers
When rate limited, the response includes helpful headers:
X-RateLimit-Limit: Maximum requests allowed in the windowX-RateLimit-Remaining: Requests remaining in current windowX-RateLimit-Reset: ISO timestamp when the rate limit resetsRetry-After: Seconds to wait before retrying
Responses
{
"error": "Rate limit exceeded",
"retryAfter": 45,
"resetAt": "2024-01-15T10:30:00.000Z"
}