Nyilvános API

OAuth-alkalmazások

Ha nem a saját fiókodat kezeled, hanem másokét: authorization code folyamat kötelező PKCE-vel és lejáró tokenekkel.

Do you need OAuth?

What you're buildingWhat to use
A script or automation for your own workspace.API key. See the Authentication page.
An AI agent for your own calendar.MCP key. See the MCP section.
An app that other people use with their own Posty accounts.OAuth. This page.
Most readers don't need this

If you're writing code for your own account, an API key is simpler and can do the same things. You need OAuth when your users grant your app access with their own Posty accounts.

The flow

  1. 1
    Register the app
    A workspace superadmin can authorize an app. You provide the redirect URIs when you register it.
  2. 2
    Send the user to the authorization page
    Authorization code flow with mandatory PKCE. This is where users see which permissions you are requesting.
  3. 3
    Exchange the code for a token
    Submit the code you received and the PKCE verifier to get an access token.
  4. 4
    Call the API with the token
    The token goes in the Authorization header with a Bearer prefix.
curl https://api.posty.hu/public/v1/integrations \
  -H "Authorization: Bearer pos_a_tokened"

Requirements

  • PKCE with an S256 challenge on every request. You can register a client without a secret, but not without PKCE.
  • The redirect_uri must exactly match an entry in the registered list. Prefix matches and wildcards are not allowed.
  • Tokens expire, and we rotate refresh tokens. We store tokens only in hashed form.
  • A superadmin authorizes the app for the workspace.

Tokens

The token is valid for the scopes the user consented to. On every call, those scopes are restricted by the user's current role. A role downgrade takes effect on the next call. You do not have to wait for the token to expire.

The list of scopes is the same as for API keys. See the Authentication page. A token issued for the MCP resource cannot be used on the REST API, and vice versa: the two resources have separate identifiers, and we validate the token's audience.

Metadata

Your client can discover every endpoint in the flow, so it does not have to hard-code the URLs:

DocumentURL
Authorization server metadatahttps://api.posty.hu/.well-known/oauth-authorization-server
Protected resource metadatahttps://api.posty.hu/.well-known/oauth-protected-resource
MCP resource metadatahttps://api.posty.hu/.well-known/oauth-protected-resource/mcp-oauth

The /public/v1/status response also lists them, without authentication.

Revocation

The user can revoke your app's access at any time in Posty, on the Settings → Approved Apps page. Revocation takes effect immediately: the next call made with the token returns a 401.

Handle this case: a 401 reflects the user's decision, not an error. Ask for authorization again. Do not retry with the same token.

Is something missing from this page? Email [email protected] or use the form on the Help page.