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.
The official .NET Client SDK that wraps this API is open source under the MIT license — see github.com/threeb-it/postnomic-dotnet for source, issues, and contributions.
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