Notejoy offers an OAuth 2.0 RESTful JSON API for select partners and customers.
Obtaining API Access
Please contact the Notejoy team detailing your specific use case for Notejoy's API in order to gain access.
Authentication
Notejoy implements the industry-standard OAuth 2.0 protocol for authentication. The following details Notejoy's OAuth 2.0 endpoints. Your app will be issued its own Client ID and Client Secret that can be used to complete the authentication flow.
Requesting authorization
Redirect the end user to the following url in order to allow the user to grant your application access to their Notejoy account. If the user is not currently logged in, they'll first be prompted to login or signup for Notejoy. Once logged in, they will then be asked to grant access to your application.
GET https://notejoy.com/oauth/authorize
Parameters
| Parameter | Required | Description |
|---|---|---|
| client_id | Required | Your app's Client ID |
| redirect_uri | Required | The url to redirect to after successful authorization. This url will include an authorization code parameter as well as a state parameter if you provided it. Must match the redirect_uri registered with Notejoy. |
| scope | Required | Space-separated list of required scopes from the following list: read_all, write_all. Must match the scope registered with Notejoy. |
| state | Any optional state that you want to be passed to you in the redirect_uri. |
Obtaining an access token
Once the user has completed the authorization flow and the user has been redirected back to your server via the redirect_uri, you can then make a server-side POST request to the following URL with the code you received from the redirect to obtain an access token for that user.
POST https://notejoy.com/api/1.0/oauth/token
Paramaters
| Parameter | Required | Description |
|---|---|---|
| code | Required | The authorization code you received as a parameter in the redirect after user authorization |
| client_id | Required | Your app's Client ID |
| client_secret | Required | Your app's Client Secret |
| redirect_uri | Required | The redirect uri you used in the authorization request. Must match the redirect_uri registered with Notejoy. |
Response
| Key | Description |
|---|---|
| access_token | The long-lived access token you can use to make API requests on behalf of the user. |
| expires | Timestamp of when the access token expires. |
Making API requests
Once you've obtained the long-lived access token for the user, you should store it securely in your server with the same level of security you store user passwords. You can then use this access token to make API requests on behalf of the user.
When making API requests, include the following authorization header:
Authorization: Bearer [access_token]
Endpoints
GET https://notejoy.com/api/1.0/notes/index
Returns an index of every note the authenticated user has access to. This includes both personal notes as well as notes in shared libraries.
Parameters
| Parameter | Required | Description |
|---|---|---|
| since | If specified, only returns notes that have been modified after the provided date. Date must be in ISO 8601 format. Example: "2019-10-18T22:43:47+00:00". Remember to escape the date string in the request url. To use this in a sync scenario, you could simply store the modified date of the first note in the response, which is the most recently modified note, and then provide that date as the since parameter the next time you want to sync. |
Response
Returns a notes list with the following attributes for each note.
| Key | Description |
|---|---|
| id | The note's unique id |
| notebook_id | The id of the notebook this note belongs to |
| title | The title of the note |
| url | The url of the note |
| created | The date when the note was created. In ISO 8601 date format. Example: "2019-10-18T22:43:47+00:00" |
| modified | The date when the note was last modified. In ISO 8601 date format. Example: "2019-10-18T22:43:47+00:00" |