Overview

API keys provide a simple, stateless authentication mechanism for accessing Postnomic blog content from your applications. They are designed for machine-to-machine communication and are the recommended way to authenticate Client SDK requests.

How API Keys Work

When your application makes a request to the Postnomic API using a Client SDK, the PostnomicApiKeyHandler automatically injects the API key into every HTTP request as a custom header:

X-Api-Key: pk_your_blog_key_here

The API validates this key on every request through the ApiKeyAuthenticationHandler. If the key is valid, the request is associated with the corresponding blog and processed. If the key is missing or invalid, the API returns a 401 Unauthorized response.

Key Format

All Postnomic API keys use the pk_ prefix followed by a unique identifier:

pk_myblog_production_a1b2c3d4e5

This prefix makes it easy to identify Postnomic keys in your configuration and to set up secret scanning rules in your source control.

Creating API Keys

To create a new API key:

1. Log in to the Postnomic dashboard
2. Select the blog you want to create a key for
3. Navigate to Settings → API Keys
4. Click Create API Key
5. Enter a descriptive name (e.g., "Production Website", "Staging App", "Mobile Client")
6. Copy the generated key immediately — it will not be shown again in full

Managing API Keys

From the API Keys management page, you can:

• View all keys — See a list of all keys for the blog with their names and creation dates
• Revoke keys — Permanently disable a key. Revoked keys will immediately stop working for all applications using them.

Best Practices

• Create separate keys per environment — Use distinct keys for development, staging, and production. This lets you revoke a compromised key without affecting other environments.
• Use descriptive names — Name keys after their purpose (e.g., "Company Website Production") so you know which to revoke if needed.
• Rotate keys periodically — Create a new key, update your application configuration, then revoke the old key.
• Never expose keys in client-side code — API keys should be stored on the server side. In Blazor WebAssembly apps, API calls should be proxied through your server.

Storing Keys Securely

Never commit API keys directly in source code. Use one of these approaches:

User Secrets (Development)

dotnet user-secrets set "PostnomicClient:ApiKey" "pk_your_key_here"

Environment Variables

export PostnomicClient__ApiKey="pk_your_key_here"

Azure Key Vault (Production)

Store the key in Azure Key Vault and reference it through your application's configuration provider. Postnomic's own infrastructure uses Key Vault for all secret management.

API Key vs JWT Authentication

Postnomic supports two authentication strategies:

API keys are scoped to a single blog and grant read-only access to published content. For management operations like creating posts, managing users, or updating settings, use JWT authentication through Auth0.