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 the Evernote domain (www.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.
The OAuth Flow consists of four parts:
- Generate a Temporary Token
- Request User Authorization
- Retrieve Access Token
- 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:
The request must be a GET request to the following URL:
| Method | Endpoint URL |
|---|---|
| GET | https://www.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 |
https://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://www.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://www.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://wwww.evernote.com/ |
edam_webApiUrlPrefix |
For internal use only |
https://www.evernote.com/ |
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).
- Learn how to revoke access tokens.