How to Authenticate with the Ideanote API
Updated 11 months ago
You can find the full API documentation at developer.ideanote.io
Introduction
Authentication is required for all Ideanote API endpoints. Currently Ideanote supports two different ways of authenticating:
- API Key Authentication
- JWT Authentication
Both authentication techniques are performed via HTTP Bearer Token Authentication using the Authorization header.
Authorization: Bearer <token>
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Below you can read more about details of each technique.
API Key Authentication
When to use: Automating Ideanote tasks based on a single Ideanote account.
The Ideanote API supports API keys for authenticating requests. A given API key is bound to a specific Ideanote account, so all requests made with the key will only have access to the same content and actions as the account that the key is bound to. You can view and manage your API key on the Settings > Profile page.
Strengths and weaknesses
This way of authenticating is great for building Ideanote integrations to automate different admin tasks in Ideanote (for example automatically creating or deleting Ideanote users on your workspace). We suggest generating a token from an admin account (or creating a dedicated 'bot' user).
Please remember that we also support other ways of building automations such as Zapier and Microsoft Power Automate.
Because an API key is bound to a specific Ideanote account, all actions made using this token will be made with the given user, thus making this authentication technique infeasible if you want to authenticate multiple Ideanote users.
HTTP Header
Authentication with the API is performed via HTTP Bearer Token Authentication using the Authorization header.
Authorization: Bearer <API Key>
curl https://api.ideanote.io/v1/ideas\?fields\=id \
-H "Authorization: Bearer b22d83ae3d28ce49fd1f8633360516"
JWT Authentication
When to use: Using the Ideanote API on behalf on any Ideanote account on your workspace (also accounts that haven't yet been created in Ideanote).
Ideanote also supports JWT authentication. In order to use this technique first you will have to activate it on your Ideanote workspace to preconfigure with a shared JWT secret under Settings > Security > Add > JWT. Remember that you will need to sign the JWTs with the secret corresponding to the relevant workspace.
How does this work?
The follow process describes the process of authenticating with JWT in details:
1. Issue the JWT: First you will have to issue a JWT on behalf of a user using the shared secret that you provided to Ideanote when you set up the JWT connection. We suggest issuing this JWT on your own server in order to keep the JWT Secret under your own control. The JWT that you issue will need to have three required keys: sub, subdomain and email (you can read more about the structure here).
2. Call an Ideanote endpoint with the JWT: Our server will first try to find an existing Ideanote account matching either sub or email.
a. An existing account was found: The API call will be made on behalf of the existing Ideanote user.
a. No existing account was found: If the API endpoint results in an action (such as a POST request), the user will be automatically be created on your workspace. If the API endpoint doesn't result in an action (such as a GET request), the API request will have same access as if the user was created, but no user will be created.
Strengths and weaknesses
This way of authenticating is great for building custom UI for Ideanote where iFrame embedding isn't possible (for example submitting ideas from a custom native app).
The downside of this technique is that it's more difficult to set up than using API Key Authentication because you will have to involve your own server in issuing JWT's.
JWT Structure
Ideanote expects the structure of the JWT payload to match the following:
sub: user ID in your system (required)email: email of the user that you want to issue the JWT on behalf (required)subdomain: the subdomain of your Ideanote workspace (required)name: full name of the user (optional)avatarUrl: an URL to the avatar of the user (optional)department: The department the user works in (optional).country: The country the user works in (optional)
HTTP Header
To authenticate API calls, provide the signed JWT using the Authorization header as such:
Authorization: Bearer <JWT>
curl https://api.ideanote.io/v1/ideas\?fields\=id \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwic3ViZG9tYWluIjoidGVzdCIsIm5hbWUiOiJKb2huIERvZSIsImVtYWlsIjoiam9obi5kb2VAdGVzdC5jb20iLCJpYXQiOjE1MTYyMzkwMjJ9.KKruDVHtfaD6-7oElJiLU7qVVYwidDdVz7oJPMn5Nzk"
The JWT payload in the above example is:
{
"sub": "1234567890",
"subdomain": "test",
"name": "John Doe",
"email": "john.doe@test.com",
"iat": 1516239022
}