Authentication

This guide shows you how to get Legacy Sent API (v2) credentials and send authenticated requests. Every v2 request requires two headers:

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

For why credentials travel in request headers rather than the URL or body, see API Authentication.

Get your credentials

1. Log into your Sent Dashboard.
2. Navigate to Settings → API Keys.
3. Click Generate New API Key.
4. Copy your x-sender-id and x-api-key values using the copy icon to the right of each key.

Store both values as environment variables rather than hardcoding them:

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

Send an authenticated request

Include both headers in every request (most HTTP clients let you set them once as default headers) and always call https://api.sent.dm over HTTPS. To verify your credentials:

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

A 200 response confirms your credentials work. A 401 response means authentication failed. Match the response body against the authentication errors below.

Authentication headers

Both credentials are UUIDs: exactly 36 characters, including hyphens.

Authentication errors

v2 authentication failures return 401 with a problem-details body. Two response bodies exist:

Missing or invalid sender ID (401)

Returned when the x-sender-id header is missing or is not a valid UUID:

{
  "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5.1",
  "title": "Missing or invalid sender identifier",
  "status": 401,
  "errors": {
    "generalErrors": ["Missing or invalid sender identifier"]
  }
}

Solution: Include the x-sender-id header and verify it matches your sender ID, formatted as a UUID.

Invalid or missing API key (401)

Returned when the x-api-key header is missing, or the key is not an active key belonging to the sender ID:

{
  "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5.1",
  "title": "Invalid or missing API credentials",
  "status": 401,
  "errors": {
    "generalErrors": ["Invalid or missing API credentials"]
  }
}

Solution: Include the x-api-key header and check that the key is active, belongs to the sender ID, and hasn't been rotated or deleted.

Debugging authentication issues

1. Verify credential format: both values are UUIDs, exactly 36 characters including hyphens (see Authentication headers).

2. Check environment variables:

   echo $SENT_SENDER_ID
   echo $SENT_API_KEY

3. Verify dashboard settings: confirm the API key is active in your dashboard and hasn't been rotated, disabled, or deleted.

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

Rate limits apply per customer account: requests authenticated with the same x-sender-id share one pool. For the limit values, the quick-message daily cap, and the 429 response format, see the v2 Rate Limits reference.

Next steps