Authenticate with the Notiondesk API using API keys

Every Notiondesk API request is authenticated with a bearer token: a workspace API key, or an OAuth access token for apps that act on behalf of other Notiondesk customers. This article shows how to create a Notiondesk API key, choose its scopes, send it with your requests, and rotate or revoke it.

Use an API key for automation you run for your own workspace: a script, a scheduled job, a CI step or an internal tool. If you are building an app that other Notiondesk customers connect to, use OAuth instead.

Before you start

• Your workspace is on an Enterprise plan.

• You are the workspace owner or an Admin.

Create a Notiondesk API key

1. In your Notiondesk dashboard, click Settings.

2. Under Workspace, open Developers, then API keys.

3. Click Create key.

4. Enter a Label that says what the key is for, for example CI automation or Redirect import.

5. Under Scopes, select only the scopes the integration needs. See Choose the right scopes.

6. Choose an Expiration: 30 days, 90 days, 1 year or No expiration.

7. Click Create.

8. Click Copy key and store the key in your secret manager or environment variables.

9. Click I have stored the key.

The key is shown only once. If you lose it, rotate the key to get a new secret.

Note: If Create key shows a lock and the tooltip "Available on plans with API access.", your plan does not include the API. Clicking it opens the upgrade options.

Choose the right scopes

A scope is a permission attached to a key. Each Notiondesk API route requires one scope, and a key can hold several.

Give each integration the smallest set of scopes it needs:

How workspace roles limit a key

A key never does more than the person who created it can do in your workspace.

If the creator's role changes, the key's effective scopes change with it. If the creator leaves the workspace, the key stops working. Manage roles in How to invite a team member.

Send the key with each request

Send the key in the Authorization header with the Bearer scheme:

curl "<https://api.notiondesk.so/sites>" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

A 200 OK with a list of your help centers confirms the key works. One key works for every help center in its workspace.

The same request in JavaScript:

const response = await fetch("<https://api.notiondesk.so/sites>", {
  headers: {
    Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
    "nd-version": "2026-10-16",
  },
});

const sites = await response.json();

And in Python:

import os
import requests

response = requests.get(
    "<https://api.notiondesk.so/sites>",
    headers={
        "Authorization": f"Bearer {os.environ['NOTIONDESK_API_KEY']}",
        "nd-version": "2026-10-16",
    },
)
sites = response.json()

Keep your Notiondesk API key safe

• Keep keys on your server. Never put a key in browser code, a mobile app or a public repository.

• Store keys in environment variables or a secret manager, not in source code.

• Create one key per integration, with its own label, so you can revoke one without breaking the others.

• Choose an expiration for keys used by temporary scripts.

• Rotate a key when someone who knew it leaves your team.

• Check the Last used column and revoke keys nobody uses.

Rotate or revoke a key

Open Settings > Developers > API keys and use the menu at the end of the key's row.

Rotate replaces the secret. Confirm with Rotate: the current secret stops working immediately and the new secret is shown once. Update your integration right away. An expired key cannot be rotated; create a replacement instead.

Revoke disables the key for good. Confirm with Revoke: automations using the key stop working immediately, and this cannot be undone.

Troubleshooting authentication

WWW-Authenticate: Bearer error="insufficient_scope", scope="sync"

Common questions

What's next

• Get started with the Notiondesk REST API

• Connect your app to Notiondesk with OAuth

• Handle Notiondesk API errors, rate limits, and retries