Evernote API: Module: UserStore

Enumeration: SponsoredGroupRole

Enumeration of Sponsored Group Roles

GROUP_MEMBER	1
GROUP_ADMIN	2
GROUP_OWNER	3

Struct: PublicUserInfo

Field	Type	Description	Requiredness	Default value
userId	Types.UserID		required
shardId	string		required
privilege	Types.PrivilegeLevel		optional
username	string		optional
noteStoreUrl	string		optional

This structure is used to provide publicly-available user information about a particular account.

userId:

The unique numeric user identifier for the user account.

shardId:

The name of the virtual server that manages the state of this user. This value is used internally to determine which system should service requests about this user's data.

privilege:

The privilege level of the account, to determine whether this is a Premium or Free account.

noteStoreUrl:

This field will contain the full URL that clients should use to make NoteStore requests to the server shard that contains that user's data. I.e. this is the URL that should be used to create the HTTP client transport to send messages to the NoteStore service for the account.

Struct: PremiumInfo

Field	Type	Description	Requiredness	Default value
currentTime	Types.Timestamp		required
premium	bool		required
premiumRecurring	bool		required
premiumExpirationDate	Types.Timestamp		optional
premiumExtendable	bool		required
premiumPending	bool		required
premiumCancellationPending	bool		required
canPurchaseUploadAllowance	bool		required
sponsoredGroupName	string		optional
sponsoredGroupRole	SponsoredGroupRole		optional

This structure is used to provide information about a user's Premium account.

currentTime:

The server-side date and time when this data was generated.

premium:

True if the user's account is Premium.

premiumRecurring

True if the user's account is Premium and has a recurring payment method.

premiumExpirationDate:

The date when the user's Premium account expires, or the date when the user's account will be charged if it has a recurring payment method.

premiumExtendable:

True if the user is eligible for purchasing Premium account extensions.

premiumPending:

True if the user's Premium account is pending payment confirmation

premiumCancellationPending:

True if the user has requested that no further charges to be made; the Premium account will remain active until it expires.

canPurchaseUploadAllowance:

True if the user is eligible for purchasing additional upload allowance.

sponsoredGroupName:

The name of the sponsored group that the user is part of.

sponsoredGroupRole:

The role of the user within a sponsored group.

Struct: AuthenticationResult

Field	Type	Description	Requiredness	Default value
currentTime	Types.Timestamp		required
authenticationToken	string		required
expiration	Types.Timestamp		required
user	Types.User		optional
publicUserInfo	PublicUserInfo		optional
noteStoreUrl	string		optional
webApiUrlPrefix	string		optional

When an authentication (or re-authentication) is performed, this structure provides the result to the client.

currentTime:

The server-side date and time when this result was generated.

authenticationToken:

Holds an opaque, ASCII-encoded token that can be used by the client to perform actions on a NoteStore.

expiration:

Holds the server-side date and time when the authentication token will expire. This time can be compared to "currentTime" to produce an expiration time that can be reconciled with the client's local clock.

user:

Holds the information about the account which was authenticated if this was a full authentication. May be absent if this particular authentication did not require user information.

publicUserInfo:

If this authentication result was achieved without full permissions to access the full User structure, this field may be set to give back a more limited public set of data.

noteStoreUrl:

This field will contain the full URL that clients should use to make NoteStore requests to the server shard that contains that user's data. I.e. this is the URL that should be used to create the HTTP client transport to send messages to the NoteStore service for the account.

webApiUrlPrefix:

This field will contain the initial part of the URLs that should be used to make requests to Evernote's thin client "web API", which provide optimized operations for clients that aren't capable of manipulating the full contents of accounts via the full data model. Clients should concatenate the relative path for the various servlets onto the end of this string to construct the full URL, as documented on our developer web site.

Struct: BootstrapSettings

Field	Type	Description	Requiredness	Default value
serviceHost	string		required
marketingUrl	string		required
supportUrl	string		required
accountEmailDomain	string		required
enableFacebookSharing	bool		optional
enableGiftSubscriptions	bool		optional
enableSupportTickets	bool		optional
enableSharedNotebooks	bool		optional
enableSingleNoteSharing	bool		optional
enableSponsoredAccounts	bool		optional
enableTwitterSharing	bool		optional

This structure describes a collection of bootstrap settings.

serviceHost:

The hostname and optional port for composing Evernote web service URLs. This URL can be used to access the UserStore and related services, but must not be used to compose the NoteStore URL. Client applications must handle serviceHost values that include only the hostname (e.g. www.evernote.com) or both the hostname and port (e.g. www.evernote.com:8080). If no port is specified, or if port 443 is specified, client applications must use the scheme "https" when composing URLs. Otherwise, a client must use the scheme "http".

marketingUrl:

The URL stem for the Evernote corporate marketing website, e.g. http://www.evernote.com. This stem can be used to compose website URLs. For example, the URL of the Evernote Trunk is composed by appending "/about/trunk/" to the value of marketingUrl.

supportUrl:

The full URL for the Evernote customer support website, e.g. https://support.evernote.com.

accountEmailDomain:

The domain used for an Evernote user's incoming email address, which allows notes to be emailed into an account. E.g. m.evernote.com.

enableFacebookSharing:

Whether the client application should enable sharing of notes on Facebook.

enableGiftSubscriptions:

Whether the client application should enable gift subscriptions.

enableSupportTickets:

Whether the client application should enable in-client creation of support tickets.

enableSharedNotebooks:

Whether the client application should enable shared notebooks.

enableSingleNoteSharing:

Whether the client application should enable single note sharing.

enableSponsoredAccounts:

Whether the client application should enable sponsored accounts.

enableTwitterSharing:

Whether the client application should enable sharing of notes on Twitter.

Struct: BootstrapProfile

Field	Type	Description	Requiredness	Default value
name	string		required
settings	BootstrapSettings		required

This structure describes a collection of bootstrap settings.

name:

The unique name of the profile, which is guaranteed to remain consistent across calls to getBootstrapInfo.

settings:

The settings for this profile.

Struct: BootstrapInfo

Field	Type	Description	Requiredness	Default value
profiles	list<BootstrapProfile>		required

This structure describes a collection of bootstrap profiles.

profiles:

List of one or more bootstrap profiles, in descending preference order.

Function: UserStore.checkVersion

bool checkVersion(string clientName,
                  i16 edamVersionMajor = 1,
                  i16 edamVersionMinor = 21)

This should be the first call made by a client to the EDAM service. It tells the service what protocol version is used by the client. The service will then return true if the client is capable of talking to the service, and false if the client's protocol version is incompatible with the service, so the client must upgrade. If a client receives a false value, it should report the incompatibility to the user and not continue with any more EDAM requests (UserStore or NoteStore).

@param clientName This string provides some information about the client for tracking/logging on the service. It should provide information about the client's software and platform. The structure should be: application/version; platform/version; [ device/version ] E.g. "Evernote Windows/3.0.1; Windows/XP SP3" or "Evernote Clipper/1.0.1; JME/2.0; Motorola RAZR/2.0;

@param edamVersionMajor This should be the major protocol version that was compiled by the client. This should be the current value of the EDAM_VERSION_MAJOR constant for the client.

@param edamVersionMinor This should be the major protocol version that was compiled by the client. This should be the current value of the EDAM_VERSION_MINOR constant for the client.

Function: UserStore.getBootstrapInfo

BootstrapInfo getBootstrapInfo(string locale)

This provides bootstrap information to the client. Various bootstrap profiles and settings may be used by the client to configure itself.

@param locale The client's current locale, expressed in language[_country] format. E.g., "en_US". See ISO-639 and ISO-3166 for valid language and country codes.

@return The bootstrap information suitable for this client.

Function: UserStore.authenticate

AuthenticationResult authenticate(string username,
                                  string password,
                                  string consumerKey,
                                  string consumerSecret)
    throws Errors.EDAMUserException, Errors.EDAMSystemException

This is used to check a username and password in order to create an authentication session that could be used for further actions.

This function is only availabe to Evernote's internal applications. Third party applications must authenticate using OAuth as described at dev.evernote.com.

@param username The username (not numeric user ID) for the account to authenticate against. This function will also accept the user's registered email address in this parameter.

@param password The plaintext password to check against the account. Since this is not protected by the EDAM protocol, this information must be provided over a protected transport (e.g. SSL).

@param consumerKey A unique identifier for this client application, provided by Evernote to developers who request an API key. This must be provided to identify the client.

@param consumerSecret If the client was given a "consumer secret" when the API key was issued, it must be provided here to authenticate the application itself.

@return The result of the authentication. If the authentication was successful, the AuthenticationResult.user field will be set with the full information about the User.

@throws EDAMUserException

• DATA_REQUIRED "username" - username is empty
• DATA_REQUIRED "password" - password is empty
• DATA_REQUIRED "consumerKey" - consumerKey is empty
• INVALID_AUTH "username" - username not found
• INVALID_AUTH "password" - password did not match
• INVALID_AUTH "consumerKey" - consumerKey is not authorized
• INVALID_AUTH "consumerSecret" - consumerSecret is incorrect
• PERMISSION_DENIED "User.active" - user account is closed
• PERMISSION_DENIED "User.tooManyFailuresTryAgainLater" - user has failed authentication too often

Function: UserStore.refreshAuthentication

AuthenticationResult refreshAuthentication(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMSystemException

This is used to take an existing authentication token (returned from 'authenticate') and exchange it for a newer token which will not expire as soon. This must be invoked before the previous token expires.

This function is only availabe to Evernote's internal applications.

@param authenticationToken The previous authentication token from the authenticate() result.

@return The result of the authentication, with the new token in the result's "authentication" field. The User field will not be set in the reply.

Function: UserStore.getUser

Types.User getUser(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMSystemException

Returns the User corresponding to the provided authentication token, or throws an exception if this token is not valid. The level of detail provided in the returned User structure depends on the access level granted by the token, so a web service client may receive fewer fields than an integrated desktop client.

Function: UserStore.getPublicUserInfo

PublicUserInfo getPublicUserInfo(string username)
    throws Errors.EDAMNotFoundException, Errors.EDAMSystemException, Errors.EDAMUserException

Asks the UserStore about the publicly available location information for a particular username.

@throws EDAMUserException

• DATA_REQUIRED "username" - username is empty

Function: UserStore.getPremiumInfo

PremiumInfo getPremiumInfo(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMSystemException

Returns information regarding a user's Premium account corresponding to the provided authentication token, or throws an exception if this token is not valid.

Function: UserStore.getNoteStoreUrl

string getNoteStoreUrl(string authenticationToken)
    throws Errors.EDAMUserException, Errors.EDAMSystemException

Returns the URL that should be used to talk to the NoteStore for the account represented by the provided authenticationToken. This method isn't needed by most clients, who can retrieve the correct NoteStore URL from the AuthenticationResult returned from the authenticate or refreshAuthentication calls. This method is typically only needed to look up the correct URL for a long-lived session token (e.g. for an OAuth web service).