Autentique-se com a API Notiondesk usando chaves de API.

Cada solicitação à API Notiondesk é autenticada com um token de portador: uma chave de API do espaço de trabalho ou um token de acesso OAuth para aplicativos que atuam em nome de outros clientes da Notiondesk. Este artigo mostra como criar uma chave de API da Notiondesk, escolher seus escopos, enviá-la com suas solicitações e rotacioná-la ou revogá-la.

Use uma chave de API para automações executadas em seu próprio espaço de trabalho: um script, uma tarefa agendada, uma etapa de CI ou uma ferramenta interna. Se você estiver criando um aplicativo ao qual outros clientes da Notiondesk se conectam, use OAuth .

Antes de começar

• Seu espaço de trabalho está em um plano Empresarial.

• Você é o proprietário do espaço de trabalho ou um administrador.

Crie uma chave de API Notiondesk

1. No seu painel de controle do Notiondesk, clique em Configurações .

2. Em Espaço de trabalho , abra Desenvolvedores e, em seguida, Chaves de API .

3. Clique em Criar chave .

4. Insira um rótulo que indique a finalidade da chave, por exemplo, CI automation ou Redirect import.

5. Em Escopos , selecione apenas os escopos necessários para a integração. Consulte Escolher os escopos corretos .

6. Escolha uma data de validade : 30 dias , 90 dias , 1 ano ou sem data de validade .

7. Clique em Criar .

8. Clique em Copiar chave e guarde a chave no seu gerenciador de segredos ou nas variáveis ​​de ambiente.

9. Clique em "Salvei a chave" .

A chave é mostrada apenas uma vez. Se você a perder, gire-a para obter um novo segredo.

Observação: Se a opção Criar chave exibir um cadeado e a dica de ferramenta "Disponível em planos com acesso à API.", seu plano não inclui a API. Clicar nela abrirá as opções de upgrade.

Escolha as miras corretas

Um escopo é uma permissão associada a uma chave. Cada rota da API Notiondesk requer um escopo, e uma chave pode conter vários.

Atribua a cada integração o conjunto mínimo de escopos de que ela precisa:

Como as funções do espaço de trabalho limitam uma chave

Uma tecla nunca faz mais do que a pessoa que a criou pode fazer no seu espaço de trabalho.

Se a função do criador mudar, o escopo efetivo da chave também mudará. Se o criador sair do espaço de trabalho, a chave deixará de funcionar. Gerencie funções em Como convidar um membro da equipe .

Envie a chave com cada solicitação.

Envie a chave no cabeçalho Authorization com o esquema Bearer:

Um 200 OK com uma lista de suas centrais de ajuda confirma que a chave funciona. Uma chave funciona para todas as centrais de ajuda em seu espaço de trabalho.

A mesma solicitação em JavaScript:

E em Python:

Mantenha sua chave de API Notiondesk em segurança.

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

• Mantenha as chaves no seu servidor. Nunca coloque uma chave no código do navegador, em um aplicativo móvel ou em um repositório público.

• Armazene as chaves em variáveis ​​de ambiente ou em um gerenciador de segredos, não no código-fonte.

• Crie uma chave por integração, com seu próprio rótulo, para que você possa revogar uma sem afetar as outras.

• Escolha um prazo de validade para as chaves usadas por scripts temporários.

• Gire uma tecla quando alguém que a conhecia sair da sua equipe.

• Verifique a coluna "Última utilização" e revogue as chaves que ninguém usa.

Girar ou revogar uma chave

Acesse Configurações > Desenvolvedores > Chaves de API e use o menu no final da linha da chave.

A opção "Girar" substitui o segredo. Confirme com "Girar" : o segredo atual deixa de funcionar imediatamente e o novo segredo é exibido apenas uma vez. Atualize sua integração imediatamente. Uma chave expirada não pode ser girada; crie uma chave de substituição.

Revogar desativa a chave permanentemente. Confirme com Revogar : as automações que usam a chave param de funcionar imediatamente e essa ação não pode ser desfeita.

Solução de problemas de autenticação

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

Perguntas frequentes

O que vem a seguir?

• Comece a usar a API REST Notiondesk

• Conecte seu aplicativo ao Notiondesk com OAuth

• Lidar com erros da API Notiondesk, limites de taxa e novas tentativas.