API Documentation
API Documentation
  • Overview
  • Terms & Guidelines
  • Rest API v1
    • Authentication
      • Obtain access token
      • Make authorized calls
    • Collections
      • Collection methods
      • Nested structure
      • Sharing
      • Covers/icons
    • Raindrops
      • Single raindrop
      • Multiple raindrops
    • Highlights
    • User
      • Authenticated user
    • Tags
    • Filters
    • Import
    • Export
    • Backups
  • More
    • Changelog
    • Showcase
Powered by GitBook
On this page
  • Step 1: The authorization request
  • Step 2: The redirection to your application site
  • Step 3: The token exchange
  • ♻️ The access token refresh

Was this helpful?

  1. Rest API v1
  2. Authentication

Obtain access token

PreviousAuthenticationNextMake authorized calls

Last updated 4 years ago

Was this helpful?

External applications could obtain a user authorized API token via the OAuth2 protocol. Before getting started, developers need to create their applications in and configure a valid OAuth redirect URL. A registered Raindrop.io application is assigned a unique Client ID and Client Secret which are needed for the OAuth2 flow.

This procedure is comprised of several steps, which will be described below.

If you just want to test your application, or do not plan to access any data except yours account you don't need to make all of those steps.

Just go to and open your application settings. Copy Test token and use it as described in .

Step 1: The authorization request

GET https://raindrop.io/oauth/authorize

Direct the user to our authorization URL with specified request parameters. — If the user is not logged in, they will be asked to log in — The user will be asked if he would like to grant your application access to his Raindrop.io data

Query Parameters

Name
Type
Description

redirect_uri

string

Redirect URL configured in your application setting

client_id

string

The unique Client ID of the Raindrop.io app that you registered

Here example CURL request:

curl "https://api.raindrop.io/v1/oauth/authorize?client_id=5e1c382cf6f48c0211359083&redirect_uri=https:%2F%2Foauthdebugger.com%2Fdebug"

Step 2: The redirection to your application site

When the user grants your authorization request, the user will be redirected to the redirect URL configured in your application setting. The redirect request will come with query parameter attached: code .

The code parameter contains the authorization code that you will use to exchange for an access token.

In case of error redirect request will come with error query parameter:

Error

Description

access_denied

When the user denies your authorization request

invalid_application_status

When your application exceeds the maximum token limit or when your application is being suspended due to abuse

Step 3: The token exchange

POST https://raindrop.io/oauth/access_token

Once you have the authorization code, you can exchange it for the access_token by doing a POST request with all required body parameters as JSON:

Headers

Name
Type
Description

Content-Type

string

application/json

Request Body

Name
Type
Description

grant_type

string

authorization_code

code

string

Code that you received in step 2

client_id

string

The unique Client ID of the Raindrop.io app that you registered

client_secret

string

Client secret

redirect_uri

string

Same redirect_uri from step 1

{
  "access_token": "ae261404-11r4-47c0-bce3-e18a423da828",
  "refresh_token": "c8080368-fad2-4a3f-b2c9-71d3z85011vb",
  "expires": 1209599768, //in miliseconds, deprecated
  "expires_in": 1209599, //in seconds, use this instead!!!
  "token_type": "Bearer"
}
{"error": "bad_authorization_code"}

Here an example CURL request:

curl -X "POST" "https://raindrop.io/oauth/access_token" \
     -H 'Content-Type: application/json' \
     -d $'{
  "code": "c8983220-1cca-4626-a19d-801a6aae003c",
  "client_id": "5e1c589cf6f48c0211311383",
  "redirect_uri": "https://oauthdebugger.com/debug",
  "client_secret": "c3363988-9d27-4bc6-a0ae-d126ce78dc09",
  "grant_type": "authorization_code"
}'

♻️ The access token refresh

POST https://raindrop.io/oauth/access_token

For security reasons access tokens (except "test tokens") will expire after two weeks. In this case you should request the new one, by calling POST request with body parameters (JSON):

Headers

Name
Type
Description

Content-Type

string

application/json

Request Body

Name
Type
Description

client_id

string

The unique Client ID of your app that you registered

client_secret

string

Client secret of your app

grant_type

string

refresh_token

refresh_token

string

Refresh token that you get in step 3

{
  "access_token": "ae261404-18r4-47c0-bce3-e18a423da898",
  "refresh_token": "c8080368-fad2-4a9f-b2c9-73d3z850111b",
  "expires": 1209599768, //in miliseconds, deprecated
  "expires_in": 1209599, //in seconds, use this instead!!!
  "token_type": "Bearer"
}
App Management Console
App Management Console
Make authorized calls
User will be asked if he would like to grant your application access to his Raindrop.io data