HMAC Authentication & Security

Secure your HMAC-signed OG image URLs with FastOG's HMAC-SHA256 authentication. This guide covers signing, validating, and troubleshooting every request, so you can ship dynamic Open Graph images on the fly — credit-based per render. Sign up free for 100 credits, then create your API key and HMAC secret in the dashboard (renders are watermarked until your first payment). Sign on your server once and integrate in minutes.

🚀 Quick Start

📚 Documentation Index

Core Concepts

• HMAC Signature Guide — Complete reference with algorithm details, requirements, and examples in JavaScript, PHP, and Python
• HMAC Validation — Server-side implementation details, security features, and error responses

Tutorials

• JavaScript/Node.js Tutorial — Comprehensive guide covering:

- Next.js App Router (3 patterns)

- Next.js Pages Router

- Express.js Backend

- Vanilla Node.js

- Frontend Integration Patterns (SSG, SSR, Client-Side)

- Testing & Debugging

- Common Pitfalls

• PHP/Laravel Tutorial — Coming soon
• Python Tutorial — Coming soon

Quick Reference

Algorithm

message = method + path + timestamp + apiKey
signature = HMAC-SHA256(message, hmac_secret)

URL: /api/v1/og?title=Hello&key=sk_quick_123abc&s=<signature>&t=<timestamp>

Query Parameters

Error Codes

🎯 Use Cases

Blog Posts

Generate dynamic OG images for blog posts:

const ogUrl = generateSignedOgUrl({
    template: "blog",
    title: post.title,
    subtitle: post.excerpt,
    author: post.author.name,
});

// <meta property="og:image" content="{ogUrl}" />

E-commerce Products

Create OG images for product pages:

const ogUrl = generateSignedOgUrl({
    template: "ecommerce",
    title: product.name,
    price: product.price,
    image: product.image,
});

User Profiles

Generate OG images for user profiles:

const ogUrl = generateSignedOgUrl({
    template: "profile",
    name: user.name,
    avatar: user.avatarUrl,
    bio: user.bio,
});

🔐 Security

Best Practices

Getting Your HMAC Secret

# .env
FASTOG_HMAC_SECRET=<your-64-char-hex-secret>

🧪 Testing

Generate Test URL

# Node.js
node -e "
const crypto = require('crypto');
const ts = Math.floor(Date.now() / 1000);
const msg = 'GET/api/v1/og' + ts + 'sk_quick_123abc';
const sig = crypto.createHmac('sha256', 'YOUR_HMAC_SECRET').update(msg).digest('hex');
console.log('https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=' + sig + '&t=' + ts);
"

Test with curl

curl "https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=<signature>&t=<timestamp>"

Expected Responses

• ✅ Valid signature → Returns OG image (or 422 if template params invalid)
• ❌ Expired timestamp → {"code": "expired_timestamp"}
• ❌ Invalid signature → {"code": "invalid_signature"}
• ❌ Missing params → {"code": "missing_signature"}

🛠 Troubleshooting

Signature doesn't match

Timestamp expired

• Ensure server clock is synchronized (use NTP)
• Generate timestamp immediately before making request
• Maximum allowed drift: 5 minutes

API key not found

• Verify you're using the full API key (e.g. sk_quick_123abc)
• Check the API key exists in dashboard
• Ensure key hasn't been revoked

📖 Additional Resources

• API Reference — Complete API documentation
• Security Best Practices — Detailed security guide
• Knowledge Base — Technical implementation details

❓ FAQ

A: OG images are fetched by social network crawlers (LinkedIn, Twitter, Facebook) that don't send custom headers. The signature MUST be in the URL.

A: No. Each signature is tied to a specific timestamp and expires after 5 minutes.

A: Yes. All requests to /api/v1/og require HMAC signatures.

A: Revoke the API key in the dashboard and create a new one. Each API key has its own HMAC secret.

A: Contact support for custom solutions. HMAC validation is mandatory for all public API endpoints.

🆘 Support

Need help?

• Check the JavaScript Tutorial for complete code examples
• Review the HMAC Signature Guide for algorithm details
• Contact support at [email protected]

Related

• Documentation — All FastOG guides and references
• Free OG Image Tester— Preview without an account
• Quick Start Guide — Get up and running in 5 minutes
• HMAC Signature Guide — Algorithm details
• HMAC Validation — Server-side validation