Skip to main content
Hayon connects to Tumblr using OAuth 1.0a. Unlike OAuth 2.0, this involves two round-trips: first to obtain a request token, then to exchange it for a permanent access token after you authorize the app on Tumblr.

​
How Tumblr OAuth works

Tumblr’s OAuth 1.0a flow has three steps:
  1. Hayon requests a temporary request token from https://www.tumblr.com/oauth/request_token and stores it server-side.
  2. You are redirected to Tumblr’s authorization page at https://www.tumblr.com/oauth/authorize where you approve access.
  3. Tumblr redirects back to Hayon’s callback with an oauth_verifier. Hayon exchanges the request token + verifier for a permanent access token and access token secret.
The resulting oauthToken and oauthTokenSecret are stored in your SocialAccount document and used to sign all future API requests via HMAC-SHA1.
The request token is stored in a short-lived in-memory store on the server. If you close the browser tab or take too long to authorize on Tumblr’s side, the session expires with the error Tumblr OAuth session expired. You must restart the connection flow from the beginning.

​
Connecting your Tumblr blog

1

Open platform settings

In the Hayon dashboard, navigate to Settings > Connected accounts and click Connect next to Tumblr.
2

Hayon obtains a request token

Hayon calls GET /api/platform/tumblr/connect, which contacts Tumblr’s OAuth endpoint and returns an authorization URL.
3

Authorize on Tumblr

Your browser opens Tumblr’s authorization page. Review the permissions and click Allow.
4

Callback and token exchange

Tumblr redirects you back to Hayon’s callback endpoint (GET /api/platform/tumblr/callback). Hayon exchanges the verifier for your permanent access token and fetches your blog information.
5

Primary blog selected

Hayon automatically selects your primary blog from the list of blogs on your account. The blog’s hostname (e.g. yourblog.tumblr.com) is stored as blogHostname.
6

Redirect to settings

You are redirected back to /settings where the connected Tumblr blog is displayed with your handle and avatar.

​
What Hayon stores

After a successful connection, the following fields are stored for Tumblr:
FieldDescription
connectedtrue once authorized
blogHostnameHostname of your primary blog (e.g. yourblog.tumblr.com)
auth.oauthTokenPermanent OAuth access token
auth.oauthTokenSecretOAuth access token secret (used for HMAC-SHA1 signing)
profile.handleYour Tumblr username
profile.avatarURL of your blog’s 512px avatar image
Tumblr OAuth 1.0a access tokens do not expire. Once connected, Hayon can continue using the stored tokens indefinitely unless you revoke access on Tumblr.

​
Blog selection

Hayon always connects your primary blog — the first blog marked primary: true in the Tumblr API response. If no primary blog is found, the first blog in the list is used.
If you have multiple Tumblr blogs and want to post to a secondary blog, this is not currently supported through the standard connection flow. The blogHostname is stored and used for all post operations.

​
Supported content types

Tumblr supports a rich variety of post types. Hayon’s current integration focuses on the most common:
Content typeSupported
Text postsYes
Photo posts (single image)Yes
Photo posts (multiple images)Yes
Link postsYes
Quote postsNo
Audio postsNo
Video postsNo
Chat postsNo

​
Media constraints

  • Image formats: JPEG, PNG, GIF, WebP.
  • Image size: Maximum 10 MB per image via the Tumblr API v2.
  • Images per post: Up to 10 images in a single photo post.
  • GIF support: Animated GIFs are supported on Tumblr natively.
  • Alt text: Tumblr’s NPF (Neue Post Format) supports alt text per image block.

​
Refreshing your profile

To refresh your stored Tumblr profile (handle and avatar) without reconnecting, call: 
GET /api/platform/tumblr/refresh
Authorization: Bearer <hayon-jwt>
This makes an authenticated request to https://api.tumblr.com/v2/user/info using your stored tokens and updates the handle, blogHostname, and avatar fields.

​
Disconnecting

To disconnect Tumblr, navigate to Settings > Connected accounts and click Disconnect next to Tumblr, or call: 
DELETE /api/platform/tumblr/disconnect
Authorization: Bearer <hayon-jwt>
This clears oauthToken, oauthTokenSecret, and profile data, and sets connected: false.
Disconnecting from Hayon does not revoke the OAuth token on Tumblr’s side. To fully remove Hayon’s access, visit https://www.tumblr.com/settings/apps and revoke the Hayon application.

​
Troubleshooting

This error appears when the in-memory request token has been cleaned up before the callback arrived. This happens if you take more than a few minutes on the authorization page, or if the server restarted mid-flow. Click Connect again to start a new OAuth session.
Hayon selects your primary Tumblr blog automatically. If this is not the blog you want to use, you must change which blog is set as primary in your Tumblr account settings, then disconnect and reconnect in Hayon.
The avatar URL is fetched from the Tumblr Avatar API: https://api.tumblr.com/v2/blog/{blogHostname}/avatar/512. If the avatar appears broken, use the refresh endpoint to re-fetch it.

Build docs developers (and LLMs) love

Get started for freeTalk to us