Overview
Postiz supports OAuth2 Authorization Code flow, allowing you to build third-party applications that act on behalf of Postiz users. Instead of asking users for their API key, your app redirects them to Postiz where they approve access, and you receive a token to make API calls on their behalf.OAuth tokens work with all the same Public API endpoints as API keys. The only difference is how the token is obtained.
How It Works
Implementation
Register Your OAuth App
Go to Settings > Developers > Apps in your Postiz dashboard and create an OAuth application.You will need to provide:
- App Name - displayed to users on the consent screen
- Description (optional) - explains what your app does
- Profile Picture (optional) - shown on the consent screen
- Redirect URL - where Postiz sends users after they approve/deny access
- Client ID - a public identifier for your app (starts with
pca_) - Client Secret - a secret key for token exchange (starts with
pcs_)
Redirect Users to Authorize
When a user wants to connect their Postiz account to your app, redirect them to:
Example:The user will see a consent screen showing your app’s name, description, and the permissions being requested. They can choose to Authorize or Deny.
| Parameter | Required | Description |
|---|---|---|
client_id | Yes | Your app’s Client ID |
response_type | Yes | Must be code |
state | No | A random string to prevent CSRF attacks. Recommended. |
Handle the Callback
After the user makes a decision, Postiz redirects them to your Redirect URL with query parameters.If approved:
If denied:
| Parameter | Description |
|---|---|
code | Authorization code to exchange for a token (expires in 10 minutes) |
state | The same state value you sent in the previous step |
Exchange Code for Token
Make a server-side
Response:
POST request to exchange the authorization code for an access token:| Parameter | Required | Description |
|---|---|---|
grant_type | Yes | Must be authorization_code |
code | Yes | The authorization code from the previous step |
client_id | Yes | Your app’s Client ID |
client_secret | Yes | Your app’s Client Secret |
Make API Calls
Use the access token in the The token works with all Public API endpoints:
Authorization header, just like you would with an API key:- List Integrations
- Create Posts
- View Analytics
- And all other endpoints documented in this API reference
OAuth tokens do not expire. Users can revoke access at any time from Settings > Approved Apps in their Postiz dashboard.
Managing Your App
Rotate Client Secret
If your client secret is compromised, go to Settings > Developers > Apps and click Rotate Secret. This invalidates the old secret immediately — any token exchange requests using the old secret will fail.Rotating the secret does not invalidate existing access tokens. Only new token exchange requests require the new secret.
Delete Your App
Deleting your OAuth app will:- Revoke all access tokens issued to users
- Remove the app from all users’ Approved Apps list
- This action cannot be undone
Full Example (Node.js)
Error Reference
| Error | When | Description |
|---|---|---|
invalid_client | Token exchange | Client ID or Client Secret is wrong |
invalid_grant | Token exchange | Code is invalid, expired, or already used |
unsupported_grant_type | Token exchange | grant_type is not authorization_code |
access_denied | Callback | User denied the authorization request |

