Connecting Platforms

All connect endpoints require a valid Bearer token unless noted otherwise. Callback endpoints are called by the platform and do not carry your token.

Overview

Each platform uses a different authentication mechanism. The table below summarises the flow type and available routes.

Platform	Auth type	Connect	Callback	Disconnect	Refresh
Bluesky	Direct credentials	`POST /api/platform/bluesky/connect`	—	`DELETE /api/platform/bluesky/disconnect`	`GET /api/platform/bluesky/refresh`
Tumblr	OAuth 1.0a	`GET /api/platform/tumblr/connect`	`GET /api/platform/tumblr/callback`	`DELETE /api/platform/tumblr/disconnect`	`GET /api/platform/tumblr/refresh`
Facebook + Instagram	OAuth 2.0	`GET /api/platform/facebook/connect`	`GET /api/platform/facebook/callback`	`DELETE /api/platform/facebook/disconnect`	`GET /api/platform/facebook/refresh`
Threads	OAuth 2.0	`GET /api/platform/threads/connect`	`GET /api/platform/threads/callback`	`DELETE /api/platform/threads/disconnect`	`GET /api/platform/threads/refresh`
Mastodon	OAuth 2.0	`GET /api/platform/mastodon/connect`	`GET /api/platform/mastodon/callback`	`DELETE /api/platform/mastodon/disconnect`	`GET /api/platform/mastodon/refresh`

Bluesky

Bluesky uses a direct credential exchange — there is no browser-based OAuth redirect.

Connect

Send a POST request with the user’s Bluesky identifier (handle or email) and an App Password generated from the Bluesky security settings. Hayon authenticates against the AT Protocol and stores the resulting session tokens.

curl --request POST \
  --url 'https://api.hayon.app/api/platform/bluesky/connect' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "identifier": "yourname.bsky.social",
    "appPassword": "xxxx-xxxx-xxxx-xxxx"
  }'

Required credentials

identifier

string

required

Bluesky handle (e.g. yourname.bsky.social) or registered email address.

appPassword

string

required

App Password generated in Bluesky → Settings → Privacy and Security → App Passwords. Do not use your main account password.

Disconnect

curl --request DELETE \
  --url 'https://api.hayon.app/api/platform/bluesky/disconnect' \
  --header 'Authorization: Bearer <token>'

Hayon stores the accessJwt and refreshJwt from the AT Protocol session. The refreshJwt is used to restore the session when refreshing the profile.

Tumblr

Tumblr uses OAuth 1.0a with a request-token / access-token two-step flow.

Initiate the OAuth flow

Call the connect endpoint. The response contains authUrl — redirect the user to this URL to grant access.

curl --request GET \
  --url 'https://api.hayon.app/api/platform/tumblr/connect' \
  --header 'Authorization: Bearer <token>'

Response:

{
  "success": true,
  "message": "Tumblr request token obtained",
  "data": { "authUrl": "https://www.tumblr.com/oauth/authorize?oauth_token=..." }
}

Handle the callback

Tumblr redirects the user to GET /api/platform/tumblr/callback with the following query parameters:

Parameter	Description
`oauth_token`	Temporary OAuth token from the initiation step.
`oauth_verifier`	Verification code issued by Tumblr after user approval.
`state`	Your Hayon user ID (set automatically by the server).

The callback exchanges these for a permanent oauthToken and oauthTokenSecret, fetches the user’s primary blog info, and redirects the browser to your frontend settings page.

Disconnect

curl --request DELETE \
  --url 'https://api.hayon.app/api/platform/tumblr/disconnect' \
  --header 'Authorization: Bearer <token>'

Facebook and Instagram

Facebook and Instagram are connected through a single OAuth 2.0 flow using the Meta Graph API. Connecting Facebook automatically links any Instagram Business account associated with the first Facebook Page on the account. Required OAuth scopes: instagram_basic, instagram_content_publish, instagram_manage_insights, pages_show_list, pages_read_engagement, pages_manage_posts, pages_manage_metadata, public_profile, business_management

Initiate the OAuth flow

Call the connect endpoint. The response contains url — redirect the user’s browser to this URL.

curl --request GET \
  --url 'https://api.hayon.app/api/platform/facebook/connect' \
  --header 'Authorization: Bearer <token>'

Response:

{
  "success": true,
  "message": "Facebook auth URL generated",
  "data": { "url": "https://www.facebook.com/v24.0/dialog/oauth?client_id=..." }
}

Handle the callback

Meta redirects the user to GET /api/platform/facebook/callback with a code query parameter. The server:

Exchanges code for a short-lived token, then upgrades it to a long-lived token (valid ~60 days).
Fetches the connected Facebook Pages and retrieves the Page access token.
Checks for a linked Instagram Business account on the first Page.
Stores Facebook and Instagram credentials separately.
Redirects the browser to your frontend settings page.

Disconnect

Disconnecting Facebook also clears the linked Instagram credentials.

curl --request DELETE \
  --url 'https://api.hayon.app/api/platform/facebook/disconnect' \
  --header 'Authorization: Bearer <token>'

Facebook posts use the Page access token. Instagram posts use the User (long-lived) access token. Both tokens are stored and refreshed independently.

Threads

Threads uses OAuth 2.0 via the Threads API. Required OAuth scopes: threads_basic, threads_content_publish, threads_manage_insights

Initiate the OAuth flow

Call the connect endpoint. Redirect the user’s browser to the returned url.

curl --request GET \
  --url 'https://api.hayon.app/api/platform/threads/connect' \
  --header 'Authorization: Bearer <token>'

Response:

{
  "success": true,
  "message": "Threads auth URL generated",
  "data": { "url": "https://threads.net/oauth/authorize?client_id=..." }
}

Handle the callback

Threads redirects to GET /api/platform/threads/callback with a code parameter. The server exchanges it for a short-lived token, upgrades it to a long-lived token (~60 days), fetches the user profile, and redirects the browser to your frontend settings page.

Disconnect

curl --request DELETE \
  --url 'https://api.hayon.app/api/platform/threads/disconnect' \
  --header 'Authorization: Bearer <token>'

Mastodon

Mastodon uses OAuth 2.0 against a fixed instance configured by the Hayon deployment.

Initiate the OAuth flow

Call the connect endpoint. Redirect the user’s browser to the returned authUrl.

curl --request GET \
  --url 'https://api.hayon.app/api/platform/mastodon/connect' \
  --header 'Authorization: Bearer <token>'

Response:

{
  "success": true,
  "message": "Mastodon auth URL generated",
  "data": { "authUrl": "https://mastodon.social/oauth/authorize?client_id=..." }
}

Handle the callback

Mastodon redirects to GET /api/platform/mastodon/callback with code and state (your Hayon user ID) query parameters. The server exchanges the code for an access token, fetches the user profile, and redirects the browser to your frontend settings page.

Disconnect

curl --request DELETE \
  --url 'https://api.hayon.app/api/platform/mastodon/disconnect' \
  --header 'Authorization: Bearer <token>'

Mastodon support is scoped to the instance URL configured in your Hayon deployment environment variables (MASTODON_INSTANCE_URL). Users must have an account on that specific instance.

Overview

Auth

Posts

Analytics

Platforms

Payments

Profile

Admin

Connecting Platforms

Overview

Bluesky

Tumblr

Facebook and Instagram

Threads

Mastodon

Build docs developers (and LLMs) love

Overview

Auth

Posts

Analytics

Platforms

Payments

Profile

Admin

​Overview

​Bluesky

​Tumblr

​Facebook and Instagram

​Threads

​Mastodon

Build docs developers (and LLMs) love

Overview

Bluesky

Tumblr

Facebook and Instagram

Threads

Mastodon