Authentication

SitemapHost uses API keys for programmatic access. The dashboard uses Google OAuth with session cookies, but all API endpoints require an API key.

Creating an API Key

1. Sign in to dash.sitemaphost.app
2. Go to Settings > API Keys
3. Click "Create API Key"
4. Give your key a descriptive name (e.g., "CI/CD Pipeline", "WordPress Sync")
5. Copy the key immediately -- it will not be shown again

Important: Your full API key is only displayed once at creation time. SitemapHost stores a hashed version of the key and cannot recover the original. If you lose your key, you must create a new one.

Key Format

SitemapHost API keys follow a consistent format:

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Prefix: sk_live_ (8 characters)
• Random part: 32 alphanumeric characters
• Total length: 40 characters

The sk_live_ prefix makes it easy to identify SitemapHost keys in your codebase or secret manager and helps secret-scanning tools flag accidental commits.

Sending Your API Key

You can authenticate requests using either of these headers:

X-API-Key header (recommended)

curl https://dash.sitemaphost.app/api/domains \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Authorization Bearer header

curl https://dash.sitemaphost.app/api/domains \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Both methods are equivalent. Use whichever is more convenient for your HTTP client or framework.

Authentication Errors

If your API key is missing, invalid, or expired, the API returns a 401 Unauthorized response:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key."
  }
}

Common causes:

Key Permissions

Each API key has full access to all resources owned by the account that created it. There is no per-key scope or permission system -- any key can manage all domains and sitemaps for that account.

If you need to restrict access (e.g., give a contractor access to one domain), create a separate SitemapHost account for that domain and issue a key from that account.

Managing API Keys

Listing keys

View all your API keys in Settings > API Keys. Each key shows:

• Name -- The label you gave it at creation
• Prefix -- The first 8 characters (sk_live_...) for identification
• Created -- When the key was created
• Last used -- The last time the key was used for an API request

Revoking a key

To revoke an API key:

1. Go to Settings > API Keys
2. Click the delete icon next to the key
3. Confirm the deletion

Revocation is immediate. Any requests using the revoked key will receive a 401 Unauthorized response.

Rotating keys

To rotate a key without downtime:

1. Create a new API key
2. Update your application/CI/CD to use the new key
3. Verify the new key works
4. Delete the old key

Security Best Practices

Store keys securely

Never hardcode API keys in source code. Use environment variables or a secrets manager:

# Environment variable
export SITEMAPHOST_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

// Read from environment
const apiKey = process.env.SITEMAPHOST_API_KEY;

Use secret scanning

Enable secret scanning in your Git hosting provider to catch accidental commits:

• GitHub -- Enable "Secret scanning" in repository settings
• GitLab -- Enable "Secret Detection" CI template
• Bitbucket -- Use the "Secret scanning" add-on

The sk_live_ prefix helps these tools identify SitemapHost keys automatically.

Limit exposure

• Use separate keys for different environments (staging vs. production)
• Rotate keys periodically (every 90 days is a good practice)
• Revoke keys for team members who leave
• Never share keys over unencrypted channels (email, Slack DMs)

Server-side only

API keys should only be used in server-side code. Never include them in:

• Client-side JavaScript (browser)
• Mobile app source code
• Public repositories
• Frontend environment variables (e.g., NEXT_PUBLIC_*)

Example: Environment Variables in CI/CD

GitHub Actions

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - run: node scripts/push-sitemap.mjs
        env:
          SITEMAPHOST_API_KEY: $

Vercel

Add SITEMAPHOST_API_KEY in your project's Settings > Environment Variables. Do not use the NEXT_PUBLIC_ prefix.

Docker

# Pass at runtime, not build time
CMD ["node", "push-sitemap.mjs"]

docker run -e SITEMAPHOST_API_KEY=sk_live_xxx myapp

Next Steps

• API Overview -- Base URL, rate limits, and response format
• Upload Endpoint -- Start uploading sitemaps
• Domains Endpoint -- Manage your domains