Authentication

Overview

All /v1/* endpoints require authentication via the Authorization header using a Bearer token:

Authorization: Bearer <token>

API Keys

API keys are the recommended authentication method for server-side and programmatic use. They are long-lived, easy to manage, and do not require any external SDKs.

Creating an API Key

You can create API keys in two ways:

Via the Dashboard:

1. Go to Dashboard > Settings > API Keys.
2. Click Create API Key.
3. Enter a descriptive name and select an expiration period.
4. Copy the key immediately.

Via the API:

curl -X POST https://api.docmap.io/v1/api-keys \
  -H "Authorization: Bearer <existing-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "expiresIn": "90d"
  }'

Key Format

API keys follow the format:

dm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are 72 characters long and always begin with the dm_live_ prefix.

Expiration Options

When creating a key, you can choose from these expiration periods:

• 30 days
• 60 days
• 90 days
• 1 year
• Never (no expiration)

WARNING

Keys that never expire are convenient but carry higher risk if compromised. Use the shortest expiration that meets your needs.

Limits

Each account can have a maximum of 10 active API keys at any time. Revoke unused keys to free up slots.

Example Request

cURL

curl https://api.docmap.io/v1/extractions \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

const response = await fetch('https://api.docmap.io/v1/extractions', {
  headers: {
    'Authorization': `Bearer ${process.env.DOCMAP_API_KEY}`,
  },
})

Error Responses

If authentication fails, the API returns a 401 Unauthorized response:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token."
  }
}

Common causes:

• Missing Authorization header
• Malformed token (wrong prefix or format)
• Expired API key
• Revoked API key

Security Best Practices

DANGER

Never expose API keys in client-side code, public repositories, or browser environments. API keys grant full access to your account's API and should be treated as secrets.

Follow these guidelines to keep your API credentials secure:

1. Store keys in environment variables -- Never hardcode API keys in source code. Use environment variables or a secrets manager.

   # .env file (never commit this)
   DOCMAP_API_KEY=dm_live_your_api_key

   // Read from environment
   const apiKey = process.env.DOCMAP_API_KEY

2. Rotate keys periodically -- Create new keys and retire old ones on a regular schedule, even if you have no reason to suspect compromise.

3. Revoke compromised keys immediately -- If a key is accidentally exposed (e.g., committed to a public repo), revoke it in Dashboard > Settings > API Keys right away and create a replacement.

4. Use the shortest reasonable expiration -- Choose an expiration period that balances convenience with security. For most production use cases, 90 days is a good default.

5. Use separate keys for different environments -- Create distinct keys for development, staging, and production. This limits the blast radius if one key is compromised and makes it easier to rotate keys without downtime.

6. Add your .env file to .gitignore -- Ensure your environment files are never committed to version control.

   # .gitignore
   .env
   .env.local
   .env.*.local