Authentication Guide

Secure, simple, and scalable – Learn how to authenticate with the Sent API using header-based authentication that provides enterprise-grade security with developer-friendly implementation.

Quick Authentication Overview

The Sent API uses header-based authentication with two required credentials that ensure secure access to your messaging resources while maintaining data isolation and separation.

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

🚀 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: Save Your Credentials

# Your credentials will look like this:
SENT_SENDER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SENT_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Quick tip: On the API Keys page in your Sent Dashboard, you can easily copy both your x-sender-id and x-api-key using the copy icon on the right of each key.

Step 3: Environment Setup

Store your credentials securely using environment variables:

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

Authentication Method

Header-Based Authentication

All Sent API endpoints require two authentication headers with every request:

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

Authentication Flow

Here's what you need to know as a developer:

That's it! Every request needs both headers, and you'll get either your data or an authentication error.

What You Need to Do

1. Include Required Headers: Add x-sender-id and x-api-key to every request
2. Handle Responses: Check for 200 (success) or 401 (authentication error)
3. Use HTTPS: Always use https://api.sent.dm for secure requests

Pro Tip: Store your credentials in environment variables and include them in your HTTP client's default headers.

Common Authentication Errors

Missing Headers (401)

{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Header x-api-key not found",
  "type": "about:blank"
}

Solution: Ensure both x-sender-id and x-api-key headers are included.

Invalid Sender ID (401)

{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Invalid x-sender-id",
  "type": "about:blank"
}

Solution: Verify your sender ID is correct and properly formatted as a UUID.

Invalid API Key (401)

{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Invalid API credentials!",
  "type": "about:blank"
}

Solution: Check that your API key is active and hasn't been rotated or deleted.

Credential Mismatch (401)

{
  "status": 401,
  "title": "Unauthorized",
  "detail": "API key does not match sender ID",
  "type": "about:blank"
}

Solution: Ensure your API key belongs to the specified sender ID.

Debugging Authentication Issues

1. Verify Credentials Format

   • Sender ID and API key should be a valid UUID format
   • Sender ID and API key must each be exactly 36 characters long and include hyphens (e.g., xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

2. Check Environment Variables

   echo $SENT_SENDER_ID
   echo $SENT_API_KEY

3. Test with cURL

   curl -v -X GET https://api.sent.dm/v1/contacts \
     -H "x-sender-id: $SENT_SENDER_ID" \
     -H "x-api-key: $SENT_API_KEY"

4. Verify Dashboard Settings

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

Security Best Practices - API Key Management

Do's

• Store in Environment Variables: Never hardcode credentials
• 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

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:

• Rate limits are applied per sender ID
• Different endpoints have different limits
• Authentication failures don't count toward rate limits

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

Ready to Authenticate? Next Steps

Now that you understand authentication, here's how to put it into practice: