Partner OAuth

Let your customers connect their DropInBlog account to your product.

Who this is for

Partner OAuth is for companies that want to build DropInBlog into their own product, such as an SEO tool, a content platform or a site builder. Your customers click a Connect DropInBlog button in your app, sign in to DropInBlog, approve the connection, and your app can then create and update posts on their blogs.

If you only want to use the API with your own DropInBlog account, you don't need any of this. Create an API key in your DropInBlog account instead, as described in the API Reference.

1. Get your client credentials

OAuth clients are set up by our team, so you can't create one yourself. Email [email protected] with:

  • Your product's name. Your customers see it on the DropInBlog approval screen.
  • Your redirect URL(s). The exact URL on your side that DropInBlog sends people back to after they approve, such as https://yourapp.com/integrations/dropinblog/callback. It must match character for character, so include every URL you will use (for example production and staging).

We'll send you back a client ID and a client secret. Keep the secret on your server. Never put it in a browser, mobile app or public repository. If it leaks, ask us for a new one.

2. Send the customer to DropInBlog

When a customer clicks your connect button, redirect their browser to:

https://app.dropinblog.com/oauth/authorize
    ?client_id=YOUR_CLIENT_ID
    &redirect_uri=https://yourapp.com/integrations/dropinblog/callback
    &response_type=code
    &scope=
    &state=RANDOM_VALUE
ParameterRequiredDescription
client_idYesThe client ID we gave you.
redirect_uriYesOne of the redirect URLs you gave us, exactly as registered. URL-encode it.
response_typeYesAlways code.
scopeYesLeave it empty. The connection gets the same access as the customer's private API key.
stateYesA random value you store in the customer's session. DropInBlog sends it back unchanged so you can check the response is for them.

The customer signs in to DropInBlog (or creates an account) and sees an approval screen with your product's name. They click Authorize or Deny.

A customer who has already connected your app is sent straight back with a new code, without seeing the approval screen again.

3. Handle the redirect

DropInBlog sends the browser back to your redirect_uri.

If the customer approved:

https://yourapp.com/integrations/dropinblog/callback?code=def50200...&state=RANDOM_VALUE

If the customer denied:

https://yourapp.com/integrations/dropinblog/callback?state=RANDOM_VALUE&error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.

Check that state matches the value you stored before doing anything else. The code can be used once and expires after 10 minutes.

4. Exchange the code for a token

From your server, POST to the token endpoint:

curl -X POST https://app.dropinblog.com/oauth/token \
  -H "Accept: application/json" \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d redirect_uri=https://yourapp.com/integrations/dropinblog/callback \
  -d code=def50200...

The redirect_uri must be the same one you used in step 2.

{
  "token_type": "Bearer",
  "expires_in": 2592000,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "refresh_token": "def50200..."
}

Store the access_token, refresh_token and the expiry time (now plus expires_in seconds) against the customer in your database, encrypted. An access token lasts 30 days and a refresh token lasts 365 days.

Refreshing a token

Before the access token expires, or when a call returns 401, exchange the refresh token for a new pair. Each refresh returns a new access token for another 30 days and a new refresh token for another 365 days, and the old refresh token stops working, so always store the new one. As long as you refresh at least once a year, the customer never has to connect again.

curl -X POST https://app.dropinblog.com/oauth/token \
  -H "Accept: application/json" \
  -d grant_type=refresh_token \
  -d refresh_token=def50200... \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d scope=

5. Call the API

Send the access token as a Bearer token on every request to https://api.dropinblog.com:

curl https://api.dropinblog.com/v2/me/blogs \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json"

A token acts as the customer who connected it. First call List blogs to get the blogs they own, and let the customer pick one if there's more than one. Use that blog's id as {blog_id} in the other endpoints, such as Create a post.

The token is a private key. It can create and update posts, categories, authors and FAQs, and, unlike a private API key, read them back, drafts and scheduled posts included. The Rendered endpoints, which output HTML for showing a blog on a website, need a public key and answer 403 with code 1004.

Disconnecting

Customers can disconnect your app at any time under Connected Apps on their API Keys page. That revokes your access and refresh tokens, so API calls return 401 and refreshing returns invalid_grant. When a refresh fails, the customer needs to connect again: send them back through step 2.

Errors

WhenResponse
client_id is wrong or redirect_uri isn't registeredThe customer sees invalid_client on DropInBlog and is not sent back to you.
The customer clicks DenyRedirect to your redirect_uri with error=access_denied.
Wrong client_secret at /oauth/token401 with {"error": "invalid_client"}
Code already used, expired, or redirect_uri doesn't match400 with {"error": "invalid_grant"}
Refresh token expired, already used, or the app disconnected400 with {"error": "invalid_grant"}
Token is invalid, expired, or the customer disconnected401 with {"message": "Unauthenticated."}
Token used on a Rendered endpoint403 with code 1004
blog_id isn't one of the customer's blogs403 with code 1000