Authentication

All Unmarkdown™ API endpoints require authentication via API keys, with one exception: the Demo Publish endpoint, which requires no authentication.

API Key Format

API keys follow a predictable format:

um_<64 hexadecimal characters>

Example: um_a1b2c3d4e5f6... (68 characters total).

The um_ prefix makes it easy to identify Unmarkdown™ keys in your codebase and to configure secret scanners.

Creating API Keys

1. Sign in to Unmarkdown™.
2. Open Settings from your avatar menu.
3. Navigate to the API tab.
4. Click Create API Key and give it a name.
5. Copy the key immediately. It is shown only once.

Each account can have up to 2 active API keys. This allows you to rotate keys without downtime.

Using API Keys

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

curl https://api.unmarkdown.com/v1/documents \
  -H "Authorization: Bearer um_your_api_key_here"

const res = await fetch('https://api.unmarkdown.com/v1/documents', {
  headers: {
    'Authorization': 'Bearer um_your_api_key_here'
  }
});

import requests

res = requests.get(
    'https://api.unmarkdown.com/v1/documents',
    headers={'Authorization': 'Bearer um_your_api_key_here'}
)

Security

• Hashed storage. API keys are hashed with SHA-256 before storage. The raw key is never saved on the server.
• One-time display. The full key is shown only at creation time. If you lose it, delete the key and create a new one.
• Never logged. API keys are excluded from server logs and error reports.
• HTTPS only. All API requests must use HTTPS. HTTP requests are rejected.

Key Rotation

To rotate a key without downtime:

1. Create a new API key (you can have up to 2).
2. Update your application to use the new key.
3. Verify the new key works.
4. Delete the old key from Settings.

Common Errors

Error	Cause	Solution
Missing Authorization header	No header sent	Add Authorization: Bearer um_... header
Invalid Authorization format	Wrong format	Use Bearer <key>, not Basic or raw key
Invalid or revoked API key	Key deleted or wrong	Check the key is correct and active in Settings