Getting started overview

Integrating with the Tumblr API involves a series of steps focused on authentication and request formulation. The Tumblr API primarily uses OAuth 1.0a for secure authentication, which differs from the more commonly adopted OAuth 2.0 standard in modern APIs. Developers must first create a Tumblr account, register an application, and then implement the OAuth 1.0a handshake to acquire user-specific access tokens.

Once authenticated, the API allows for various programmatic interactions, including creating new posts, retrieving blog information, and managing user content. This guide outlines the essential steps to get an application connected and performing its initial API call.

Here is a quick reference for the getting started process:

Step What to do Where
1. Create a Tumblr Account Sign up for a free Tumblr user account. Tumblr Sign-Up Page
2. Register Your Application Create a new application to obtain Consumer Key and Consumer Secret. Tumblr Application Registration
3. Understand OAuth 1.0a Familiarize yourself with the OAuth 1.0a authentication flow. Tumblr API OAuth 1.0a Documentation
4. Obtain Request Token Initiate the OAuth flow to get a temporary request token. Your application's backend
5. Authorize Request Token Direct the user to Tumblr to authorize your application. Tumblr authorization URL
6. Exchange for Access Token Swap the authorized request token for a permanent access token and secret. Your application's backend
7. Make Your First Request Use the Consumer Key, Consumer Secret, Access Token, and Access Token Secret to sign and send an API call. Your application's backend

Create an account and get keys

To interact with the Tumblr API, you must first establish a developer presence. This involves creating a standard Tumblr user account and then registering an application within the Tumblr developer portal.

  1. Create a Tumblr Account: If you do not already have one, navigate to the Tumblr sign-up page and create a new account. This account will be associated with your developer applications and will serve as the owner of any blogs you manage through the API.

  2. Register Your Application: Once logged in, go to the Tumblr API Applications page. Click the "Register an application" button. You will need to provide the following details:

    • Application Name: A descriptive name for your application.
    • Application Website: The URL of your application's homepage.
    • Default callback URL: This URL is crucial for the OAuth 1.0a flow. After a user authorizes your application, Tumblr will redirect them to this URL, appending the OAuth verifier. For testing, a local development URL (e.g., http://localhost:3000/callback) can be used.
    • Application Description: A brief explanation of what your application does.
    • Contact Email: An email address for support or communication regarding your application.

    After submitting, Tumblr will provide you with a Consumer Key and a Consumer Secret. These are your application's unique identifiers and credentials. Keep them secure, as they are essential for all subsequent authentication steps.

Your first request

Making your first request to the Tumblr API requires implementing the OAuth 1.0a authentication flow to obtain user-specific access tokens. This process involves several steps:

  1. Obtain a Request Token: Your application initiates the OAuth flow by requesting a temporary "request token" from Tumblr. This step typically involves sending a signed HTTP request to the /oauth/request_token endpoint along with your Consumer Key and Consumer Secret. The response will contain a oauth_token (the request token) and oauth_token_secret.

    POST https://www.tumblr.com/oauth/request_token
Authorization: OAuth oauth_consumer_key="YOUR_CONSUMER_KEY",
               oauth_signature_method="HMAC-SHA1",
               oauth_timestamp="CURRENT_TIMESTAMP",
               oauth_nonce="RANDOM_NONCE",
               oauth_version="1.0",
               oauth_callback="YOUR_CALLBACK_URL",
               oauth_signature="GENERATED_SIGNATURE"

  2. Authorize the Request Token: Redirect the user’s browser to Tumblr’s authorization page, appending the obtained request token. The URL format is https://www.tumblr.com/oauth/authorize?oauth_token=YOUR_REQUEST_TOKEN. The user will log in to their Tumblr account (if not already) and grant permission for your application to access their blog data. Upon successful authorization, Tumblr redirects the user back to your specified Default Callback URL, including an oauth_verifier parameter.

  3. Exchange for an Access Token: Upon receiving the callback with the oauth_verifier, your application makes a final request to Tumblr's /oauth/access_token endpoint. This request is signed using your Consumer Key, Consumer Secret, the original request token, request token secret, and the new oauth_verifier. If successful, Tumblr responds with a permanent oauth_token (access token) and oauth_token_secret (access token secret). These credentials can be stored securely and used for all subsequent API calls on behalf of that user.

    POST https://www.tumblr.com/oauth/access_token
Authorization: OAuth oauth_consumer_key="YOUR_CONSUMER_KEY",
               oauth_signature_method="HMAC-SHA1",
               oauth_timestamp="CURRENT_TIMESTAMP",
               oauth_nonce="RANDOM_NONCE",
               oauth_version="1.0",
               oauth_token="YOUR_REQUEST_TOKEN",
               oauth_verifier="THE_OAUTH_VERIFIER_FROM_CALLBACK",
               oauth_signature="GENERATED_SIGNATURE"

  4. Make an Authenticated API Call: With the Consumer Key, Consumer Secret, Access Token, and Access Token Secret, you can now sign and make requests to any protected API endpoint. For example, to retrieve information about a user's blog, you might call the /v2/blog/{blog-identifier}/info endpoint:

    GET https://api.tumblr.com/v2/blog/staff.tumblr.com/info
Authorization: OAuth oauth_consumer_key="YOUR_CONSUMER_KEY",
               oauth_token="YOUR_ACCESS_TOKEN",
               oauth_signature_method="HMAC-SHA1",
               oauth_timestamp="CURRENT_TIMESTAMP",
               oauth_nonce="RANDOM_NONCE",
               oauth_version="1.0",
               oauth_signature="GENERATED_SIGNATURE"

    The signature generation for each step requires careful implementation according to the OAuth 1.0a specification for signing requests. Many programming languages have libraries that abstract this complexity, such as oauthlib for Python or oauth-1.0a for Node.js.

Common next steps

After successfully making your first API call, you can explore more advanced functionalities offered by the Tumblr API. Here are some common next steps:

  • Posting Content: Develop functionality to create various types of posts (text, photo, quote, link, chat, audio, video) on a user's blog. The Tumblr API post creation endpoint allows for rich content submission.

  • Retrieving Posts: Implement features to fetch posts from a specific blog, filtered by type, tag, or date. This enables displaying user content within your application. Refer to the Tumblr blog posts documentation for details.

  • User Interactions: Explore endpoints for liking posts, reblogging content, or following other blogs. These features allow for deeper integration with Tumblr's social aspects. The Tumblr user likes API provides methods for managing liked posts.

  • Error Handling: Implement robust error handling mechanisms to gracefully manage API rate limits, authentication failures, and other potential issues. The Tumblr API error handling guide provides information on common error codes and their meanings.

  • Rate Limits: Understand and manage API rate limits to ensure your application doesn't get temporarily blocked. The Tumblr API imposes limits on the number of requests your application can make within a given timeframe. Details on specific limits are available in the Tumblr API limits section.

  • Webhooks (Post Notifications): For real-time updates, consider setting up webhooks to receive notifications when new posts are created on a specific blog. While not explicitly detailed in the main API v2 documentation, Tumblr offers webhook functionality for post notifications, which can be useful for applications requiring immediate data synchronization.

Troubleshooting the first call

Encountering issues during the initial API setup is common, especially with OAuth 1.0a. Here are some common problems and troubleshooting steps:

  • Invalid oauth_signature: This is the most frequent issue with OAuth 1.0a. The signature is highly sensitive to every parameter, including the order of parameters, encoding, and the base string calculation. Double-check:

    • Parameter Order: Parameters must be sorted alphabetically before signing.
    • Encoding: Ensure all parameters are properly URL-encoded (RFC 3986).
    • Signing Key: The signing key combines your Consumer Secret and Access Token Secret (for subsequent calls) with an ampersand (&).
    • Timestamp and Nonce: Ensure the oauth_timestamp is current and oauth_nonce is a unique, random string for each request.
    • HTTP Method and URL: Verify the HTTP method (GET, POST) and the base URL are exactly as expected by Tumblr.

    Refer to the OAuth 1.0a Core Specification on Signature Parameters for detailed guidance on signature generation.

  • Incorrect oauth_callback URL: During the request token phase, if the oauth_callback URL provided in your initial request does not exactly match one of the URLs registered for your application, Tumblr will reject the request or fail to redirect properly after authorization. Ensure the scheme (HTTP/HTTPS), host, path, and port match precisely.

  • Expired or Invalid Tokens: Request tokens are temporary. If too much time passes between obtaining a request token and exchanging it for an access token, it might expire. Access tokens, while generally long-lived, can also be revoked by the user or Tumblr. Ensure you are using the correct and current tokens for each step.

  • Missing Permissions: If your API call returns an "unauthorized" or "forbidden" error, verify that the user who authorized your application granted the necessary permissions (scopes). While Tumblr's OAuth 1.0a doesn't explicitly use scopes in the same way OAuth 2.0 does, the authorization step implicitly grants access based on the application's nature and the user's consent.

  • Rate Limiting: If you make too many requests within a short period, you might hit Tumblr's rate limits, resulting in 429 Too Many Requests errors. Implement exponential backoff or ensure your application respects the limits outlined in the Tumblr API documentation on limits.

  • Using an Outdated Library: If you are using an OAuth 1.0a client library, ensure it is up-to-date and correctly implements the specification. Sometimes, subtle deviations in older libraries can lead to signature mismatches.