Ideanote API

The Ideanote API is a RESTful API that allows developers to interact with Ideanote's platform. It uses standard HTTP methods, JSON-encoded responses, and requires API keys for authentication. The API is versioned to ensure backwards compatibility, with the current version being v1. All API requests must be made over HTTPS.

Please refer to the full API documentation for detailed information and examples on each API endpoint and its parameters at developer.ideanote.io.

Authentication

The API uses API keys for authentication, which are bound to a specific Ideanote account. API keys are required for all requests, and they grant access to the content and actions associated with the linked account. API requests without authentication will fail. The API key should be provided in the Authorization header as a bearer token.

Rate Limit

To ensure stability, the API employs rate limiting. All requests are IP-rate-limited to a maximum of 60 requests per minute. Exceeding the rate limit will result in a 429 response status code.

Query Parameters

Each API endpoint supports various query parameters that allow filtering, ordering, and limiting the returned data. The common query parameters are:

• text: Searches and filters content based on the given text.
• limit: Limits the total amount of entries to retrieve from the endpoint (maximum 20).
• offset: Adjusts the offset of items returned.
• orderBy: Orders entities by a specific field on the model.
• filter: Builds and combines filters to narrow down the received content.
• fields: Specifies a comma-separated list of fields to return for performance and nested entities.

API Endpoints

Users

The user object represents members created on the workspace. Users can be retrieved, created, updated, and deleted. The API allows admins and owners of the workspace to create new users, and it automatically sends invitation emails to the created users.

Missions

The mission object represents a mission collection and contains ideas. Missions can be listed, retrieved, created, updated, and deleted. Deleting a mission will delete all ideas within it.

Ideas

The idea object represents ideas within a mission. Ideas can be listed, retrieved, created, and updated. Deleting an idea will permanently remove it.

Comments

The comment object represents comments made on ideas. Comments can be listed, retrieved, updated, and deleted.

Teams

Teams are created on the workspace and can be assigned to users. Teams can be listed, retrieved, created, updated, and deleted.

Statuses

The status object represents statuses created on the workspace. Each idea points to a status.

Authenticate with the Ideanote API

Authentication is required for all Ideanote API endpoints. Currently Ideanote supports two different ways of authenticating:

1. API Key Authentication
2. 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.

Authenticate via API Key

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.

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"

Authenticate via JWT

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 > Authentication > 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.‍
3. An existing account was found: The API call will be made on behalf of the existing Ideanote user.‍
4. 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.

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:

1. sub: user ID in your system (required)
2. email: email of the user that you want to issue the JWT on behalf (required)
3. subdomain: the subdomain of your Ideanote workspace (required)
4. name: full name of the user (optional)
5. avatarUrl: an URL to the avatar of the user (optional)
6. department: The department the user works in (optional).
7. 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}

‍