API Authentication

Machine-to-machine requests authenticate with an API key. Dashboard sessions authenticate with a short-lived JWT. Both are accepted on the same endpoints; a key is what you want for integrations and scripts.

Getting Your API Key

Key Management Endpoints

Keys can also be managed over the API. These routes require an admin session or an admin-scoped key.

curl -X POST "https://api.ddmarc.com/api/v1/api-keys" \
  -H "X-API-Key: $DDMARC_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI pipeline",
    "scope": "read",
    "expires_in_days": 90
  }'

{
  "id": 7,
  "name": "CI pipeline",
  "key": "ddmarc_4f1c...b93a",
  "key_prefix": "4f1c8ad2",
  "scope": "read",
  "expires_at": "2026-10-17T09:14:00Z",
  "created_at": "2026-07-19T09:14:00Z"
}

key is present only on this 201 response. Subsequent GET calls return key_prefix, scope, last_used_at and expires_at only, alongside the plan allowance fields limit, used and can_create.

Making Authenticated Requests

curl -X GET "https://api.ddmarc.com/api/v1/domains" \
  -H "X-API-Key: $DDMARC_API_KEY"

const response = await fetch(
  "https://api.ddmarc.com/api/v1/domains",
  { headers: { "X-API-Key": process.env.DDMARC_API_KEY } }
);
const domains = await response.json(); // bare array

import os, requests

response = requests.get(
    "https://api.ddmarc.com/api/v1/domains",
    headers={"X-API-Key": os.environ["DDMARC_API_KEY"]},
)
domains = response.json()  # list[dict]

API Key Properties

Scopes

Scope is chosen when the key is created and cannot be changed afterwards. Scopes are hierarchical: admin satisfies anything that requires write, which satisfies anything that requires read. A request that needs more authority than the key carries fails with 403.

Grant the narrowest scope that works. A read key that leaks cannot delete a domain.

Plan Limits

Programmatic API access requires the Protect plan or higher. Requests are metered hourly and pooled across the whole organization rather than per key.

Hitting the hourly cap returns 429 with Retry-After: 3600. No X-RateLimit-* headers are sent on successful responses, so track usage on your side.

Authentication Errors

{
  "detail": "Invalid API key"
}

Errors are always a flat object with a detail field. There is no nested errorobject and no machine-readable error code — branch on the HTTP status.

The dashboard and the mobile view authenticate with JWTs rather than API keys. You only need this if you are building something that signs a human in.

• Access tokens are short-lived. They expire after 15 minutes and are sent as Authorization: Bearer or as an httpOnly access_token cookie.
• Refresh tokens last 7 days and rotate. Call POST /api/v1/auth/refresh to exchange one; each refresh token is single-use, so replaying an old one fails.
• Several sign-in methods exist. Password, magic link, one-time code, passkeys (WebAuthn), and Google or Microsoft single sign-on, all under /api/v1/auth.
• Scopes do not apply to JWTs.A signed-in user's authority comes from their role. Scope enforcement is specific to API keys.

Managing API Keys

Continue to API Reference