Authentication

Authenticating with the Evernote Cloud API using OAuth


Introduction

The OAuth flow is the a process a user goes through to authorize your application to access their Evernote account on their behalf. The user must approve access from an Evernote domain (www.evernote.com or sandbox.evernote.com). After approval is granted (or rejected) Evernote will then redirect the user back to your application along with the information required to retrieve an access token which will allow you to access Evernote on behalf of the user.

Developer Tokens

To quickly test the Evernote API on your own account, Get a Developer Token »

The OAuth Flow consists of four parts:

  1. Generate a Temporary Token
  2. Request User Authorization
  3. Retrieve Access Token
  4. Next Steps for Accessing the API


1. Generate a Temporary Token

First you’re application must request Evernote generate a temporary token. A sample request is below:

Note: For production access replace sandbox.evernote.com with www.evernote.com.

The request must be a GET request to the following URL:

Method Endpoint URL
GET https://sandbox.evernote.com/oauth

As a part of this request you must provide a number of URL-encoded parameters including a callback URL (you can use “localhost” for development purposes) where the user will be directed after the user chooses to authorize or reject your application.

Temporary Token Request Parameters

A full list of required parameters can be seen in the table below. If you don't have an API key (oauth_consumer_key) you can get one here: Get an API Key

Name
Description
Sample
oauth_callback
URL that is redirected to after the user authorizes your application access
http://www.foo.com
oauth_consumer_key
The API key used to identify your application
sampleKey
oauth_nonce
*
3166905818410889691
oauth_signature
*
xCYjTiyz7GZiElg1uQaHGQ6I
oauth_signature_method
*
HMAC-SHA1
oauth_timestamp
*
1429565574
oauth_version
*
1.0

Note: * The parameters oauth_nonce, oauth_signature, oauth_signature_method, oauth_timestamp, and oauth_version are parameters that are provided by most Evernote SDKs and OAuth libraries. If you are interested in developing an OAuth1 library for your platform please see the OAuth1 3LO specification.

Temporary Token Response

Upon transmission of a valid request you will receive the following response:

This response contains the following parameters:

Name
Description
Sample
oauth_token
Temporary OAuth token
sampleKey-121.14C...
oauth_callback_confirmed
boolean to determine if the callback URL is set
true


2. Request User Authorization

After you have retrieved the temporary token from Evernote you must redirect the user to Evernote for the user to approve access of their Evernote account to your application.

Redirection URL

Your application must use the value of the oauth_token parameter, retrieved in the last step, when redirecting the user to https://sandbox.evernote.com/OAuth.action to begin the authorization process as demonstrated in this sample redirection URL:

After the user has granted or rejected access to their Evernote account the user will be redirected back to the URL specified in the oauth_callback parameter in your temporary token request. A sample redirect URL can be seen below with the parameters expected of a user that has granted access to their Evernote account:

Callback URL Parameters
Name
Description
Sample
oauth_token
Temporary Token
sampleKey-121.14C...
oauth_verifier
(Optional) Present only if the user grants access to your application
40793F8BAE15D4E3B6DD5CA8AB4BF62F
sandbox_lnb
Boolean for API key permissions (see permissions for more info)
false

Please note that the callback for rejected and authorized apps will be the same with the exception of that a rejected callback will not contain the parameter oauth_verifier, as seen in the example below:



3. Retrieve Access Token

The following is an example of a request to retrieve an access token:

The request must be a GET request to the following URL:

Method
Endpoint URL
GET
https://sandbox.evernote.com/oauth

The request must also include the URL-encoded OAuth-signed parameters listed in the table below. Please note that if you did not receive the oauth_verifier parameter in the callback the user did not grant your application access to their Evernote account and you cannot make a valid access token request

Access Token Request Parameters
Name
Description
Sample
oauth_consumer_key
The API key used to identify your application
sample-api-key-4121
oauth_token
Temporary OAuth Token
sampleKey-121.14C...
oauth_verifier
OAuth verify provided at callback if the user grants access
40793F8BAE15D4E3B6DD5CA8AB4BF62F
oauth_nonce
*
3166905818410889691
oauth_signature
*
xCYjTiyz7GZiElg1uQaHGQ6I
oauth_signature_method
*
HMAC-SHA1
oauth_timestamp
*
1429565574
oauth_version
*
1.0

Note: * The parameters oauth_nonce, oauth_signature, oauth_signature_method, oauth_timestamp, and oauth_version are provided by most Evernote SDKs and OAuth libraries. If you are interested in developing an OAuth1 library for your platform please see the OAuth1 3LO specification.

Access Token Response

If successful you will receive a response similar to the sample below:

the response will contain the following parameters:

Name
Description
Sample
oauth_token
Access token to access the API on behalf of the user
S=s432:U=4a535ee:E=15430d...
oauth_token_secret
will always be empty
edam_shard
Shard of the user’s personal notes
s432
edam_userId
User ID of the user (useful for webhook notifications)
77936110
edam_expires
expiration date of the token (UNIX timestamp in milliseconds)
1461107889411
edam_noteStoreUrl
URL of the note store of the user’s personal notes
https://sandbox.evernote.com/shard/s432/notestore
edam_webApiUrlPrefix
For internal use only
https://sandbox.evernote.com/shard/s432/
Access Token Expiration


Each access token has an expiration date. By default, the duration of access token validity is 1 year from the date of issue. The user can alter this duration to 1 day, 1 week or 1 month. In all these cases (including tokens valid for 1 year), the expiration date will be included as the parameter edam_expires. The value of this parameter will be a standard UNIX timestamp in units of milliseconds indicating the date and time of expiration.



4. Next Steps for Accessing the API

Using the value of oauth_token above (it should start with the form S=s432:U=4a535ee:E=154d..) you can now make requests to the API on behalf of the user that approved your application! You can use this token to perform actions in Evernote like saving content and data to notes and notebooks and (if your API key has the permission to do so) reading notes, notebooks, tags, performing searches and retrieving business data for use in your application.

Now that you have an authentication token here are some suggested next steps to dive in with the API:

  • Take a look at our SDK's sample code using your authentication token
  • Explore the API methods you can call using your access token
  • Understand Evernote's sharded service architecture for NoteStore, which can vary by user (you can learn more about sharding and Evernote's architecture in this tech blog post).
Activating an API key

Please note that while the samples for this page show URls beginning with https://sandbox.evernote.com all examples will also work on production by altering the URLs to begin with https://www.evernote.com. We recommend beginning your application development on the sandbox.

To move your key to production please request your API key be activated on production.

Stay on top of what's happening in the Evernote developer community.