Authentication
How authenticated requests work in the public PostMantis API.
API authentication model
All public API requests use a Bearer API key. Account administration — connecting profiles, creating keys, billing — is dashboard-only. Agents and automations authenticate with a scoped PostMantis API key and never touch provider OAuth directly.
All public API requests use a Bearer API key.
Authorization: Bearer <your-api-key>Where API keys come from
API keys are created and managed in the PostMantis dashboard.
API keys are instance-specific. A key created on one PostMantis deployment only works against that same deployment and database.
That is also where a human:
- connects provider accounts
- reconnects expired accounts
- creates keys for agents and automations
- chooses what each key is allowed to access
The public API does not include endpoints for:
- creating keys
- rotating keys
- revoking keys
- performing provider OAuth or account onboarding
Scope model
Permission scope
Restrict a key to read-only or write-capable behavior.
Provider scope
Restrict a key to allowed providers such as X, LinkedIn, or YouTube.
Profile scope
Restrict a key to specific connected accounts or publishing profiles.
Permission scope
A read key is for observers, dashboards, monitoring jobs, and systems that only need visibility.
Typical access includes:
- reading profiles
- reading posts
- reading related workflow state
- reading runtime results that the key is allowed to see
A write key is for systems that actually publish.
Typical access includes:
- creating posts
- updating drafts or scheduled posts
- publishing drafts
- canceling scheduled posts
- creating uploads
Platform and profile scope
If a key is restricted, the API should only expose and allow actions for the allowed subset.
Examples:
- a key scoped to
xshould not be able to publish to LinkedIn or YouTube - a key scoped to two profiles should only see those two connected profiles
- a read-only key should not be able to create or publish posts
What an API key can access
An API key grants access only to the allowed portion of the publishing surface.
That may include:
- profiles
- posts
- uploads
The exact visible and writable resources depend on the key scope.
For posts, visibility is all-or-nothing: a key can read a post only when every delivery on that post is inside the key's allowed scope.
Error shape
Public API failures use application/problem+json.
Typical authentication failures look like this:
{
"type": "https://postmantis.com/problems/unauthorized",
"title": "Unauthorized",
"status": 401,
"detail": "Missing bearer token",
"code": "unauthorized"
}Treat detail as the human-readable explanation and code as the stable machine-friendly field.
Best practices
Keep keys server-side
Never expose publishing keys in a browser or client app.
Use least privilege
Prefer read keys for observers and write keys only for systems that publish.
Scope narrowly
Limit each key to the minimum required providers and profiles.
Treat key scope as immutable
If access requirements change, revoke the old key and create a new one.
Separate environments
Use different keys for development and production.
Example
curl https://postmantis.com/api/profiles \
-H "Authorization: Bearer $POSTMANTIS_API_KEY"