Authentication Guide

Secure, simple, and scalable – The Sent API v3 uses header-based authentication with a single API key that identifies your account and authorizes all requests.

Authentication Overview

The Sent API v3 uses header-based authentication with one required header:

x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Your account is automatically identified from the API key. No additional sender ID or customer identifier is required.

🚀 Getting Started: Need API credentials? Visit your Sent Dashboard to generate your keys instantly.

Getting Your Credentials

Step 1: Access Your Dashboard

1. Log into your Sent Dashboard
2. Navigate to Settings → API Keys
3. Click Generate New API Key

Step 2: Understand Key Types

Step 3: Environment Setup

Store your credentials securely using environment variables:

# .env file - Production
SENT_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# .env file - Development
SENT_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Security Note: Never commit your .env file to version control. Add it to .gitignore immediately.

Authentication Method

Header-Based Authentication

All Sent API endpoints require the x-api-key header with every request:

Example Request

curl -X GET https://api.sent.dm/v3/contacts \
  -H "x-api-key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Why Header-Based?

• 🔒 Secure: Credentials are sent in headers, not in the URL or body
• 🚀 Simple: No complex OAuth flows or token exchanges required
• ⚡ Fast: Direct authentication on every request with minimal overhead
• 🔄 Stateless: No session management or token refresh required

Common Response Headers

All responses include these headers for debugging and monitoring:

Common Authentication Errors

Missing API Key (401)

{
  "success": false,
  "error": {
    "code": "AUTH_001",
    "message": "User is not authenticated",
    "doc_url": "https://docs.sent.dm/errors/AUTH_001"
  },
  "meta": {
    "request_id": "req_xxx",
    "timestamp": "2024-01-01T00:00:00Z",
    "version": "v3"
  }
}

Solution: Ensure the x-api-key header is included in all requests.

Invalid or Expired API Key (401)

{
  "success": false,
  "error": {
    "code": "AUTH_002",
    "message": "Invalid or expired API key",
    "doc_url": "https://docs.sent.dm/errors/AUTH_002"
  },
  "meta": { ... }
}

Solution:

• Verify your API key is correct
• Check if the key has been revoked or expired
• Generate a new key from the dashboard if needed

Insufficient Permissions (403)

{
  "success": false,
  "error": {
    "code": "AUTH_004",
    "message": "Insufficient permissions for this operation",
    "doc_url": "https://docs.sent.dm/errors/AUTH_004"
  },
  "meta": { ... }
}

Solution: Verify the API key has the required permissions for the operation.

Debugging Authentication Issues

1. Verify API Key Format

   • API keys are UUID format (e.g., xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
   • Both production and test keys use the same format
   • Key should be complete (no truncation)

2. Check Environment Variables

   echo $SENT_API_KEY

3. Test with cURL

   curl -v -X GET https://api.sent.dm/v3/me \
     -H "x-api-key: $SENT_API_KEY"

4. Verify Dashboard Settings

   • Check if API key is active in your dashboard
   • Confirm key hasn't been disabled or rotated

Security Best Practices

Do's

• ✅ Store in Environment Variables: Never hardcode credentials in source code
• ✅ Use Different Keys: Separate keys for development, staging, and production
• ✅ Rotate Regularly: Update API keys every 90 days or after security incidents
• ✅ Monitor Usage: Track API key usage patterns and set up alerts
• ✅ Restrict Access: Limit who has access to production API keys
• ✅ Use HTTPS: Always use https://api.sent.dm for secure requests

Don'ts

• ❌ Never Commit to Version Control: Add .env to .gitignore
• ❌ Avoid Client-Side Exposure: Never send API keys to browsers or mobile apps
• ❌ Don't Share Keys: Each environment and team member should have unique keys
• ❌ Avoid Logging: Don't log API keys in application logs

Rate Limiting

Authentication works seamlessly with our rate limiting system:

• Standard endpoints: 200 requests/minute
• Sensitive endpoints (e.g., secret rotation): 10 requests/minute
• Rate limit headers included on 429 responses:
  • Retry-After: Seconds until you can retry
  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Unix timestamp when the window resets

📚 Learn More: See our Rate Limits Documentation for detailed information.