An overview of authenticating with the Evernote Cloud API using OAuth
- Applications use OAuth to authenticate to a user's Evernote account
- Our SDKs help make OAuth easy
- Developer tokens allow you to access your personal Evernote account without using OAuth
Before your application can do anything with the Cloud API, it needs to ask the user to authorize access to their Evernote account. This authorization is performed using OAuth, which allows the user to grant access to their account without sharing their Evernote password.
If you are using the API to access only your Evernote account for personal use, you don't need to go through the OAuth authorization process. Instead, you can get a developer token that will allow you to access your account through the API.
Note that, at this time, developer tokens are not supported by the iOS SDK. Instead, the iOS SDK provides a layer of abstraction on top of the usual OAuth implementation in our other SDKs, making implementing OAuth in your application much easier.
Regardless of whether you use OAuth or developer tokens, your application will end up with an authentication token that can be used to call API functions. Once you have authenticated, move on to the core concepts chapter to learn how to access the contents of a user's account.
Introduction to OAuth
Evernote supports the same standard OAuth authentication process used by other popular web services like Twitter and Google. In many cases, you don't need to understand the details of the process. Your application simply uses an existing OAuth library that handles all of the details:
- iOS and Android: the Evernote SDK handles OAuth for you.
- PHP, Python and Ruby: the Evernote SDKs contain sample code demonstrating how to integrate popular third party OAuth SDKs into your web application.
- Other languages: we're working on SDKs and sample code.
Authentication tokens can expire or be revoked
The OAuth token that you receive will allow your application to access the user's account for 1 year. The user can revoke this token at any time. Your application needs to handle API calls that fail because the authentication token is no longer valid. It is typically best to prompt the user to reauthorize access to their account.
By default, Evernote authentication tokens grant your application permission to create, read and update objects in a user's Evernote account. You will not have access to permanently delete (expunge) objects. When you request activation of your API key on our production service, we will work with you to assign only the minimum required permissions to your application.
Detailed OAuth instructions
You will need the following information in order to build an OAuth client (consumer) that works with Evernote:
- Temporary credential request URI: https://evernoteHost/oauth
- Resource owner authorization URI: https://evernoteHost/OAuth.action
- Token request URI: https://evernoteHost/oauth
- Security: HTTPS for all requests
- Supported signature methods: PLAINTEXT & HMAC-SHA1
- Supported OAuth parameter locations: HTTP Authorization header & request URI query parameters
When you're developing your app in the sandbox, evernoteHost will be sandbox.evernote.com. Once you activate your API key and switch to our production service, you'll need to change this to www.evernote.com.
The gory details of OAuth are described in section 2 of RFC 5849:
Obtain client credentials
Your Evernote API key consumer key and consumer secret are used as the OAuth client credentials.
Obtain temporary credentials
As described in RFC 5849 section 2.1, your web service will make a direct request to Evernote's servers to get temporary credentials (aka request token) that can be used to perform secure authentication for a single user. This request will be sent over SSL and will be authenticated using your client credentials.
The request parameter oauth_callback must contain the callback URL to be used in the following step. The response will contain the temporary credentials: the oauth_token and oauth_token_secret. If you used the signature method PLAINTEXT, the oauth_token_secret will be the empty string.
Sample temporary credentials request:
Sample temporary credentials response:
Resource owner authorization
Once you have temporary credentials, you direct your user (the resource owner) to Evernote's web site to approve access by your application as described in RFC 5849 section 2.2.
For security purposes, all of the OAuth authorization web interfaces make use of the X-FRAME-OPTIONS HTTP response header to prohibit them from being shown in an iframe.
After logging in or creating an account (if necessary), the user is shown information that identifies your service and specifies the access that will be granted. The user can then authorize or deny access to their Evernote account.
After the resource owner authorizes you to access their Evernote account, they will be redirected to the callback URL that you provided in the previous step. The request to your callback will include the oauth_token parameter containing the temporary credential identifier that was authorized and the oauth_verifier parameter that you will need in the following step.
Sample authorization URL:
Sample callback URL:
Create an account within the OAuth flow
You can have users create their account within the OAuth flow. To do this, simply add the parameter
preferRegistration=true to the OAuth URL.
On non-iOS platforms, users can always create an account within the OAuth flow. This parameter specifies whether Evernote will default to showing "login" or "register" for users who are not already logged in. On iOS, Evernote will not show a registration option unless you specify this parameter.
Obtain token credentials (Access Token)
After you receive a successful callback from Evernote, you will exchange the temporary credentials for an authentication token (aka token credentials or access token) as described in RFC 5849 section 2.3.
The URL to obtain the authentication token is the same as the one to get temporary credentials: https://www.evernote.com/oauth. Evernote determines what you want by the presence of the mandatory oauth_token parameter in the request. You must also include the mandatory oauth_verifier parameter that you obtained in the previous step.
The response will contain the mandatory oauth_token and oauth_token_secret elements (URL encoded), and will also contain an edam_noteStoreUrl entry, which specifies the correct URL for subsequent Cloud API calls, the edam_userId entry, which identifies the authenticated user's Evernote user ID, and the edam_epires entry, which indicates the time at which the authentication token expires.
Make sure that you URL-decode the authentication token and NoteStore URL that you receive from the Evernote server!
Sample token credentials request:
Sample token credentials response
In this example, the OAuth token credential identifier is:
And the NoteStore URL for this user is:
In the example above, the authenticated user account has the Evernote user ID 161. You may need this value if you choose to use webhooks to receive notifications when notes are created or updated. Evernote does not use the token credential secret, which will always be the empty string.
Access the Evernote account
The token credential identifier retrieved via OAuth is an Evernote authentication token that can be used for calls to call Cloud API functions. The token is provided as a parameter to the function calls - OAuth "authenticated requests" are not used to access the Evernote account.
After authenticating succesfully, you'll also receive a string containing the URL used to access the NoteStore service that contains the user's notes. Because of Evernote's sharded service architecture, this URL can vary by user. If you're curious, you can learn more about sharding and our service architecture in this tech blog post by our CTO.
Using developer tokens
If you are building a script or application that will only access your own personal Evernote account, then you don't need to implement OAuth. Instead, you can get a developer token that will allow you to use the API to access your own personal Evernote account.
First, get a developer token for the Evernote sandbox service. Once you've built you application, you can request a developer token for the production service.
Then, write your code. Simply pass your developer token as the authenticationToken parameter in each API call.