Overview
The Postnomic API supports two authentication strategies: JWT Bearer tokens for user-level access and API Keys for machine-to-machine content access. Choose the method that matches your integration scenario.
JWT Bearer Authentication (Auth0)
JWT Bearer authentication is used for the Postnomic dashboard and any integration that needs full API access on behalf of a user.
How It Works
- Your application redirects the user to Auth0 for login
- Auth0 authenticates the user and issues a JWT (JSON Web Token)
- Your application includes the JWT in the
Authorizationheader on every API request - The Postnomic API validates the token and identifies the user via their
IdentityUserId
Request Format
curl -X GET https://api.postnomic.com/api/blogs \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
When to Use JWT
- Dashboard operations — Creating blogs, managing posts, updating settings
- User-specific actions — Anything that requires knowing which user is performing the action
- Full API access — JWTs grant access to all authenticated endpoints
Token Refresh
JWT tokens have a limited lifetime. The Postnomic dashboard uses the offline_access scope to obtain refresh tokens and automatically refreshes expired tokens. If you are building a custom integration, implement token refresh logic in your application.
API Key Authentication
API Keys provide a simple, stateless authentication method for accessing published blog content. They are the recommended method for Client SDK integrations.
How It Works
- Create an API key for your blog in the dashboard
- Include the key in the
X-Api-Keyheader on every request - The
ApiKeyAuthenticationHandlervalidates the key and associates the request with the correct blog
Request Format
curl -X GET https://api.postnomic.com/api/public/blogs/my-blog \
-H "X-Api-Key: pk_your_blog_key_here"
When to Use API Keys
- Client SDK integrations — Embedding a blog in your .NET application
- Public content access — Reading published posts, blog info, and comments
- Server-to-server calls — Fetching content for static site generation or caching
Key Characteristics
| Property | Value |
|---|---|
| Header | X-Api-Key |
| Prefix | pk_ |
| Scope | Single blog (read-only) |
| Expiration | No expiration (valid until revoked) |
| Rate limits | Standard API rate limits apply |
Comparison
| JWT Bearer | API Key | |
|---|---|---|
| Access level | Full API (user-level) | Read-only (blog-level) |
| Authentication | Auth0 login flow | Static key in header |
| Use case | Dashboard, management | Client SDKs, public content |
| Identity | Linked to specific user | Linked to specific blog |
| Expiration | Time-limited (refreshable) | No expiration |
| Revocation | Through Auth0 | Through dashboard |
Unauthenticated Endpoints
Some endpoints are publicly accessible without any authentication. These are located under the /api/public/ path and include:
- Blog information retrieval
- Published post listings and details
- Public analytics (view counts)
- Comment submission (when moderation is configured)
These endpoints are served by the PublicBlogsController, PublicPostsController, and PublicAnalyticsController.
Error Responses
Authentication failures return standard HTTP error codes:
- 401 Unauthorized — Missing or invalid authentication credentials
- 403 Forbidden — Valid credentials but insufficient permissions for the requested action