Security

API Authentication

The DDMARC API uses API keys for authentication. All API requests must include a valid API key in the Authorization header.

Quick Start

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer your_api_key_here

Getting Your API Key

Navigate to Settings

Log into your DDMARC dashboard and go to Settings → API.

Create New API Key

Click Create API Key and give it a descriptive name (e.g., "Production Server" or "CI/CD Pipeline").

Copy and Store Securely

Copy the API key immediately. For security, it will only be shown once. Store it in a secure location like a secrets manager.

Making Authenticated Requests

cURL

curl -X GET \
  "https://api.ddmarc.com/v1/domains" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

JavaScript (fetch)

const response = await fetch('https://api.ddmarc.com/v1/domains', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  }
});

Python (requests)

import requests

response = requests.get(
  'https://api.ddmarc.com/v1/domains',
  headers={'Authorization': f'Bearer {API_KEY}'}
)

API Key Properties

Key Format

API keys are 40-character alphanumeric strings prefixed with ddm_.

ddm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Permissions

API keys inherit the permissions of the user who created them. Organization admins can create keys with full access.

Expiration

API keys do not expire by default. You can set an optional expiration date when creating the key for added security.

Rotation

We recommend rotating API keys periodically. Create a new key, update your applications, then revoke the old key.

Authentication Errors

Code	Error	Description
401	Unauthorized	Missing or invalid API key
401	Key Expired	API key has passed its expiration date
401	Key Revoked	API key has been revoked
403	Forbidden	Key lacks permission for this action

Error Response Example

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key",
    "status": 401
  }
}

Security Best Practices

Never expose keys in client-side code. API keys should only be used server-side.
Use environment variables. Never hardcode API keys in your source code.
Rotate keys regularly. Create new keys and revoke old ones periodically.
Use separate keys per environment. Different keys for development, staging, and production.
Monitor API key usage. Check the dashboard for unusual activity patterns.

Managing API Keys

View Keys

See all active API keys, their names, creation dates, and last used timestamps.

Revoke Keys

Immediately revoke compromised or unused keys. Revoked keys cannot be reactivated.

Regenerate

Create a new key with the same permissions. Remember to update your applications.

Documentation