Uwierzytelnij się za pomocą interfejsu API Notiondesk, używając kluczy API

Każde żądanie API Notiondesk jest uwierzytelniane za pomocą tokena nośnika: klucza API obszaru roboczego lub tokenu dostępu OAuth w przypadku aplikacji działających w imieniu innych klientów Notiondesk. W tym artykule pokazano, jak utworzyć klucz API Notiondesk, wybrać jego zakresy, wysłać go wraz z żądaniami oraz dokonać rotacji lub unieważnienia.

Użyj klucza API do automatyzacji, którą uruchamiasz we własnym obszarze roboczym: skryptu, zaplanowanego zadania, kroku CI lub narzędzia wewnętrznego. Jeśli tworzysz aplikację, z którą łączą się inni klienci Notiondesk, użyj zamiast tego protokołu OAuth .

Zanim zaczniesz

• Twoja przestrzeń robocza jest objęta planem Enterprise.

• Jesteś właścicielem obszaru roboczego lub administratorem.

Utwórz klucz API Notiondesk

1. Na pulpicie nawigacyjnym Notiondesk kliknij Ustawienia .

2. W obszarze roboczym otwórz Deweloperzy , następnie Klucze API .

3. Kliknij Utwórz klucz .

4. Wprowadź etykietę określającą, do czego służy klucz, na przykład CI automation lub Redirect import.

5. W sekcji „Zakresy” wybierz tylko te zakresy, których potrzebuje integracja. Zobacz „Wybór odpowiednich zakresów” .

6. Wybierz okres ważności : 30 dni , 90 dni , 1 rok lub Brak okresu ważności .

7. Kliknij Utwórz .

8. Kliknij Kopiuj klucz i zapisz klucz w menedżerze sekretów lub zmiennych środowiskowych.

9. Kliknij Zapisałem klucz .

Klucz jest wyświetlany tylko raz. Jeśli go zgubisz, obróć klucz, aby uzyskać nowy sekret.

Uwaga: Jeśli w polu „Utwórz klucz ” pojawi się kłódka i podpowiedź „Dostępne w planach z dostępem do API”, Twój plan nie obejmuje API. Kliknięcie go otworzy opcje aktualizacji.

Wybierz odpowiednie zakresy

Zakres to uprawnienie przypisane do klucza. Każda trasa API Notiondesk wymaga jednego zakresu, a klucz może zawierać ich kilka.

Przypisz każdej integracji najmniejszy zestaw zakresów, jakiego potrzebuje:

Jak role w przestrzeni roboczej ograniczają klucz

Klucz nigdy nie robi więcej, niż osoba, która go stworzyła, może zrobić w Twoim miejscu pracy.

Jeśli rola twórcy ulegnie zmianie, zakresy efektywne klucza ulegną zmianie. Jeśli twórca opuści obszar roboczy, klucz przestanie działać. Zarządzanie rolami opisano w artykule Jak zaprosić członka zespołu .

Wyślij klucz z każdym żądaniem

Wyślij klucz w nagłówku Authorization ze schematem Bearer:

200 OK z listą centrów pomocy potwierdza, że ​​klucz działa. Jeden klucz działa dla każdego centrum pomocy w jego obszarze roboczym.

To samo żądanie w JavaScript:

A w Pythonie:

Zachowaj bezpieczeństwo swojego klucza API Notiondesk

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

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();

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()

• Przechowuj klucze na serwerze. Nigdy nie umieszczaj klucza w kodzie przeglądarki, aplikacji mobilnej ani publicznym repozytorium.

• Przechowuj klucze w zmiennych środowiskowych lub w menedżerze sekretów, a nie w kodzie źródłowym.

• Utwórz jeden klucz dla każdej integracji, z własną etykietą, dzięki czemu będziesz mógł odwołać jeden z nich, nie naruszając pozostałych.

• Wybierz datę wygaśnięcia kluczy używanych przez skrypty tymczasowe.

• Obróć klucz, gdy ktoś, kto go znał, opuszcza twoją drużynę.

• Sprawdź kolumnę Ostatnio używane i unieważnij klucze, których nikt nie używa.

Obróć lub cofnij klucz

Otwórz Ustawienia > Deweloperzy > Klucze API i skorzystaj z menu na końcu wiersza kluczy.

Rotacja zastępuje klucz tajny. Potwierdź przyciskiem Rotacja : obecny klucz tajny przestaje działać natychmiast, a nowy klucz tajny jest wyświetlany jednokrotnie. Zaktualizuj integrację natychmiast. Nie można obrócić wygasłego klucza; zamiast tego utwórz klucz zastępczy.

Cofnięcie (Revoke) trwale dezaktywuje klucz. Potwierdź (Revoke) : automatyzacje używające klucza przestają działać natychmiast i nie można tego cofnąć.

Rozwiązywanie problemów z uwierzytelnianiem

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

Często zadawane pytania

Co dalej?

• Rozpocznij korzystanie z interfejsu API REST Notiondesk

• Połącz swoją aplikację z Notiondesk za pomocą protokołu OAuth

• Obsługa błędów API Notiondesk, limitów szybkości i ponownych prób