Authentication

Learn how to authenticate your API requests

API Keys

The demeterrr API uses API keys for authentication. API keys identify your organization and determine what resources you can access based on assigned scopes.

Keep your API keys secure! Treat them like passwords. Never expose them in client-side code, public repositories, or logs.

Creating an API Key

1. Log in to your demeterrr dashboard
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Assign a name and select scopes
5. Copy the key immediately (it won’t be shown again)

API Key Format

All demeterrr API keys follow this format:

dem_[43 random characters]

Example: dem_xK3p9vL2mN8qR4tY6wZ1aC5eF7gH9jK0lM2nO4pQ6rS8t

Making Authenticated Requests

Include your API key in the X-API-Key header:

cURL

curl https://app.demeterrr.com/api/v1/contacts \
  -H "X-API-Key: dem_your_api_key_here"

Alternative: Bearer Token

You can also use the Authorization header with a Bearer token:

curl https://app.demeterrr.com/api/v1/contacts \
  -H "Authorization: Bearer dem_your_api_key_here"

Authentication Errors

Missing API Key

Status: 401 Unauthorized

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Provide via X-API-Key header or Authorization: Bearer <key>"
  }
}

Invalid API Key Format

Status: 401 Unauthorized

{
  "error": {
    "code": "INVALID_API_KEY_FORMAT",
    "message": "Invalid API key format. Key must start with 'dem_'"
  }
}

Invalid or Inactive Key

Status: 401 Unauthorized

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or inactive API key"
  }
}

Expired API Key

Status: 401 Unauthorized

{
  "error": {
    "code": "EXPIRED_API_KEY",
    "message": "API key has expired"
  }
}

Key Management Best Practices

Rotate keys regularly

Create new API keys periodically and delete old ones to minimize security risks.

Use environment variables

Store API keys in environment variables, not in your source code.

export DEMETERRR_API_KEY="dem_your_key_here"

Use minimal scopes

Only grant the scopes (permissions) your integration actually needs. See Scopes for details.

Monitor usage

Check your API key usage in the dashboard to detect unusual activity.

Revoke compromised keys immediately

If you suspect a key has been exposed, delete it immediately from your dashboard.

Next Steps

Scopes

Learn about API key permissions

Quick Start

Make your first API call