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/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/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 | None (no per-key throttling is applied) |
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 /public/ path and include:
- Blog information, tags, categories, and author profiles
- Published post listings and post details (approved comments are embedded in the post detail response)
- Comment submission
- Page-view recording (write-only — there is no public endpoint that reads analytics back)
These endpoints are served by the PublicBlogsController, PublicPostsController, and PublicAnalyticsController.
The API is mounted at the root of its host. There is no
/apipath prefix —https://api.postnomic.com/blogsandhttps://api.postnomic.com/public/blogs/{blogSlug}are the real paths.
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