Authentication

All MarkdownAPI.io API endpoints require authentication using API keys. API keys are persistent credentials that never expire, making them ideal for programmatic access, AI agents, and automation.

Why API keys? They’re simple, secure, and never expire. Perfect for server-to-server communication, AI agents, scripts, and CI/CD pipelines.

Quick Start: Get Your API Key

The fastest way to get started is to create an API key through the dashboard:

1. Navigate to the API Keys page

   • Go to Dashboard → API Keys or visit markdownapi.io/dashboard/api-keys 

2. Click “Create API Key”

   • Enter a descriptive name (e.g., “Production API”, “Development”, “CI/CD Pipeline”)

3. Copy your key immediately

   • The key is shown only once and cannot be retrieved later
   • Click the copy button to save it to your clipboard

4. Start making API calls

   • Include your key in the Authorization header

Using Your API Key

Include your API key in the Authorization header with the Bearer scheme:

curl "https://markdownapi.io/api/projects" \
  -H "Authorization: Bearer YOUR_API_KEY"

import httpx
 
api_key = "sk_..."  # Your API key
 
async with httpx.AsyncClient() as client:
    response = await client.get(
        "https://markdownapi.io/api/projects",
        headers={"Authorization": f"Bearer {api_key}"}
    )
    projects = response.json()

const apiKey = "sk_...";  // Your API key
 
const response = await fetch('https://markdownapi.io/api/projects', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});
 
const projects = await response.json();

API Key Format

API keys follow the format: sk_ followed by a URL-safe random string.

Example: sk_5KJ2hN9mP3qR7sT8uV1wX4yZ6aB0cD2e

Creating API Keys

Via Dashboard (Recommended)

Creating API keys through the dashboard is the recommended method, especially for getting started.

Step-by-step guide:

1. Navigate to API Keys

   • Go to Dashboard → API Keys
   • Or visit markdownapi.io/dashboard/api-keys  directly

2. Enter a descriptive name

   • Use meaningful names that indicate the key’s purpose
   • Good examples:
     • “Production API Server”
     • “Development Testing”
     • “CI/CD Pipeline”
     • “Mobile App v2”
   • Descriptive names help you identify keys when you have multiple

3. Click “Create API Key”

   • The system generates a cryptographically secure key

4. Copy and save your key

   • A modal displays your new API key
   • This is the only time you’ll see the full key
   • Click the copy button to save it
   • Store it securely (environment variables, secrets manager, password manager)

5. Acknowledge and complete

   • Check the acknowledgment box confirming you’ve saved the key
   • Click “Done”

What you’ll see in the dashboard:

After creating a key, it appears in your API Keys list with:

• Name: The descriptive name you provided
• Key prefix: First 12 characters (e.g., sk_5KJ2hN9m...) for identification
• Created date: When the key was created
• Last used: Timestamp of most recent API call (or “Never used”)
• Status: Active or Inactive

Programmatically (For Automation)

For CI/CD pipelines, automation scripts, or programmatic key management, you can create API keys via the API.

curl -X POST "https://markdownapi.io/api/keys" \
  -H "Authorization: Bearer YOUR_EXISTING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline Key"
  }'

import httpx
 
existing_key = "sk_..."  # Your existing API key
 
async with httpx.AsyncClient() as client:
    response = await client.post(
        "https://markdownapi.io/api/keys",
        headers={"Authorization": f"Bearer {existing_key}"},
        json={
            "name": "CI/CD Pipeline Key"
        }
    )
    data = response.json()
    new_api_key = data["key"]
    print(f"New API Key: {new_api_key}")
    print("Save this key - it won't be shown again!")

const existingKey = "sk_...";  // Your existing API key
 
const response = await fetch('https://markdownapi.io/api/keys', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${existingKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'CI/CD Pipeline Key'
  })
});
 
const data = await response.json();
const newApiKey = data.key;
console.log(`New API Key: ${newApiKey}`);
console.log('Save this key - it won\'t be shown again!');

Response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "key": "sk_5KJ2hN9mP3qR7sT8uV1wX4yZ6aB0cD2e",
  "key_prefix": "sk_5KJ2hN9m",
  "name": "CI/CD Pipeline Key",
  "created_at": "2025-01-09T10:00:00Z",
  "expires_at": null,
  "warning": "This is the only time you'll see this key. Please save it securely!"
}

Managing Your API Keys

Viewing Your Keys

Access your API keys dashboard at /dashboard/api-keys to view all your keys.

Information displayed:

• Key Name: The descriptive name you provided
• Key Prefix: First 12 characters (e.g., sk_5KJ2hN9m...)
• Status Badge: Active or Inactive
• Created Date: When the key was created
• Last Used: Most recent API request timestamp
  • Shows “Never used” if the key hasn’t been used yet
  • Updates after each successful API request

Revoking API Keys

Revoke a key when it’s no longer needed or if it’s been compromised:

1. Navigate to API Keys

   • Go to Dashboard → API Keys

2. Find the key

   • Locate it by name or prefix

3. Click “Revoke”

   • Click the red “Revoke” button next to the key

4. Confirm revocation

   • Read the warning in the confirmation dialog
   • Applications using this key will immediately lose access
   • Click “Revoke Key” to confirm

5. Verify

   • The key’s status changes to “Inactive”
   • The key remains visible but cannot be used
   • API calls with this key will receive 401 errors

Rotating API Keys

For security best practices, rotate your API keys regularly (every 90 days recommended).

Zero-downtime rotation process:

1. Create a new API key

   • Give it a descriptive name (e.g., “Production Key v2”)
   • Copy and save the new key

2. Update your applications

   • Deploy the new key to all services
   • Test thoroughly in staging first

3. Verify everything works

   • Monitor your applications
   • Check for authentication errors
   • Confirm all services are using the new key

4. Revoke the old key

   • Only after confirming the new key works everywhere
   • This ensures zero downtime

Best practice timeline:

• Day 1: Create and deploy new key
• Day 2-7: Monitor for issues, keep both keys active
• Day 8: Revoke old key once confident new key is working

Key Usage Tracking

Monitor your API key usage to:

• Verify keys are being used by the intended applications
• Identify unused keys that can be revoked
• Detect unusual activity patterns
• Track which services are most active

The “Last used” timestamp updates after each successful API request, helping you identify:

• Active keys: Recently used (within days)
• Dormant keys: Haven’t been used in weeks/months
• Unused keys: Never used (may have been created but not deployed)

Security Best Practices

Essential Rules

1. Never commit keys to version control

   • Add keys to .gitignore
   • Use environment variables or secrets management
   • Review commits before pushing

2. Use environment variables

   • Development: .env files (not committed)
   • Production: Cloud secrets manager (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault)
   • CI/CD: Platform secrets (GitHub Secrets, GitLab CI/CD variables)

3. Rotate keys regularly

   • Every 90 days recommended
   • Immediately if compromised
   • Use zero-downtime rotation process

4. Use separate keys per environment

   • Development key for local testing
   • Staging key for pre-production
   • Production key for live services
   • CI/CD key for automated builds

5. Revoke unused keys immediately

   • Don’t leave dormant keys active
   • Clean up after projects end
   • Revoke keys from departing team members

Advanced Security

# .env file (add to .gitignore)
MARKDOWN_API_KEY=sk_5KJ2hN9mP3qR7sT8uV1wX4yZ6aB0cD2e

# AWS Secrets Manager
aws secretsmanager create-secret \
  --name markdown-api-key \
  --secret-string "sk_5KJ2hN9mP3qR7sT8uV1wX4yZ6aB0cD2e"
 
# GCP Secret Manager
echo -n "sk_5KJ2hN9mP3qR7sT8uV1wX4yZ6aB0cD2e" | \
  gcloud secrets create markdown-api-key --data-file=-

# .github/workflows/deploy.yml
- name: API Call
  env:
    API_KEY: ${{ secrets.MARKDOWN_API_KEY }}
  run: |
    curl -H "Authorization: Bearer $API_KEY" \
      https://markdownapi.io/api/projects

Development:  sk_dev_...  (for local testing)
Staging:      sk_stg_...  (for pre-production)
Production:   sk_prod_... (for live services)
CI/CD:        sk_ci_...   (for automated tests)

Error Responses

401 Unauthorized

Authentication failed. The API key is missing, invalid, or revoked.

Causes:

• Missing Authorization header
• Invalid or malformed API key
• Revoked API key
• Incorrect header format

Example Response:

{
  "detail": "Invalid authentication credentials"
}

Solutions:

1. Verify the Authorization header is included
2. Check the key format: Authorization: Bearer sk_...
3. Ensure the key hasn’t been revoked
4. Verify you’re using the correct key (not a truncated/prefix version)
5. Create a new key if the old one is lost or compromised

403 Forbidden

Valid authentication but insufficient permissions.

Causes:

• Attempting to access resources owned by another user
• Trying to modify resources you don’t have access to
• API key lacks required permissions

Example Response:

{
  "detail": "You do not have permission to access this resource"
}

Solutions:

• Verify you own the requested resource
• Ensure you’re accessing resources in your account
• Check that you’re authenticated with the correct user’s API key

Rate Limiting

When rate limited, the API returns:

Status: 429 Too Many Requests

Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704801600

Response:

{
  "detail": "Rate limit exceeded. Try again in 1234 seconds."
}

Best Practices:

• Monitor rate limit headers in responses
• Implement exponential backoff for retries
• Cache responses when appropriate
• Batch operations when possible
• Create multiple API keys if you need higher throughput (each key has independent limits)

Complete Example

Here’s a complete workflow from creating your first API key to making API calls:

import httpx
import os
 
async def get_started_with_markdown_api():
    """Complete workflow: Get API key and make first calls."""
 
    # Step 1: Get your API key from dashboard
    # Go to https://markdownapi.io/dashboard/api-keys
    # Click "Create API Key" and copy it
    api_key = os.getenv("MARKDOWN_API_KEY")  # Store in environment variable
 
    if not api_key:
        print("❌ Please set MARKDOWN_API_KEY environment variable")
        return
 
    print(f"✓ Using API key: {api_key[:12]}...")
 
    async with httpx.AsyncClient() as client:
        # Step 2: List your projects
        projects_response = await client.get(
            "https://markdownapi.io/api/projects",
            headers={"Authorization": f"Bearer {api_key}"}
        )
        projects = projects_response.json()
        print(f"✓ You have {len(projects['projects'])} projects")
 
        # Step 3: Create a new project
        create_response = await client.post(
            "https://markdownapi.io/api/projects",
            headers={"Authorization": f"Bearer {api_key}"},
            json={"name": "My First Project"}
        )
        project = create_response.json()
        print(f"✓ Created project: {project['name']}")
 
        # Step 4: Upload a file
        with open("README.md", "rb") as f:
            upload_response = await client.post(
                f"https://markdownapi.io/api/projects/{project['id']}/files",
                headers={"Authorization": f"Bearer {api_key}"},
                files={"file": ("README.md", f, "text/markdown")}
            )
        file_data = upload_response.json()
        print(f"✓ Uploaded file: {file_data['filename']}")
 
        print("\n🎉 Success! You're ready to use the API.")
 
# Usage
# Set your API key: export MARKDOWN_API_KEY=sk_...
# Then run: await get_started_with_markdown_api()

async function getStartedWithMarkdownAPI() {
  // Step 1: Get your API key from dashboard
  // Go to https://markdownapi.io/dashboard/api-keys
  // Click "Create API Key" and copy it
  const apiKey = process.env.MARKDOWN_API_KEY;  // Store in environment variable
 
  if (!apiKey) {
    console.log("❌ Please set MARKDOWN_API_KEY environment variable");
    return;
  }
 
  console.log(`✓ Using API key: ${apiKey.substring(0, 12)}...`);
 
  // Step 2: List your projects
  const projectsResponse = await fetch('https://markdownapi.io/api/projects', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });
  const projects = await projectsResponse.json();
  console.log(`✓ You have ${projects.projects.length} projects`);
 
  // Step 3: Create a new project
  const createResponse = await fetch('https://markdownapi.io/api/projects', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name: 'My First Project' })
  });
  const project = await createResponse.json();
  console.log(`✓ Created project: ${project.name}`);
 
  // Step 4: Upload a file
  const formData = new FormData();
  formData.append('file', new Blob(['# Hello World'], { type: 'text/markdown' }), 'README.md');
 
  const uploadResponse = await fetch(
    `https://markdownapi.io/api/projects/${project.id}/files`,
    {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${apiKey}` },
      body: formData
    }
  );
  const fileData = await uploadResponse.json();
  console.log(`✓ Uploaded file: ${fileData.filename}`);
 
  console.log('\n🎉 Success! You\'re ready to use the API.');
}
 
// Usage
// Set your API key: export MARKDOWN_API_KEY=sk_...
// Then run: await getStartedWithMarkdownAPI();

Next Steps

Now that you understand authentication, you’re ready to start using the API:

• Quick Start Guide - Complete tutorial
• Projects API - Manage projects
• Files API - Upload and manage files