Conecte seu aplicativo ao Notiondesk com OAuth

O OAuth permite que outros clientes da Notiondesk conectem seu aplicativo ao espaço de trabalho deles sem compartilhar uma chave de API. O cliente faz login na Notiondesk, revisa o que seu aplicativo solicita e aprova. Seu aplicativo recebe um token de acesso para a API REST da Notiondesk, e o cliente pode revogá-lo a qualquer momento. Este artigo explica como registrar seu aplicativo, executar o fluxo de código de autorização OAuth 2.0 com PKCE, atualizar tokens e lidar com erros.

Quando usar OAuth em vez de uma chave de API

Cada rota da API Notiondesk aceita ambas as credenciais e responde da mesma maneira: com os mesmos escopos, respostas e erros.

O que seu aplicativo precisa saber

Leia os endpoints do documento de metadados do servidor de autorização em vez de codificá-los diretamente no código.

Execute seu cliente OAuth em um servidor. Clientes baseados em navegador não são suportados: mantenha a troca de tokens, os tokens e todas as chamadas de API em seu backend.

Passo 1: Registre seu aplicativo

Cadastre-se uma única vez com o registro dinâmico de clientes :

A resposta 201 Created contém seu client_id e, como você solicitou client_secret_post, um client_secret. O segredo é exibido apenas uma vez: armazene-o com seus outros segredos do servidor.

Com "token_endpoint_auth_method": "none", seu aplicativo é um cliente público sem segredos, e o PKCE protege a troca de código.

Em vez de se registrar, você pode usar o URL HTTPS de um documento de metadados do cliente como seu client_id. O Notiondesk busca o documento quando um cliente autoriza seu aplicativo e o armazena em cache por até cinco minutos.

Regras de URI de redirecionamento

curl -X POST "https://api.notiondesk.so/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Acme Reports", "redirect_uris": ["https://acme.example/oauth/callback"], "token_endpoint_auth_method": "client_secret_post"}'

• Use https ou http em um host de loopback: 127.0.0.1, localhost ou [::1].

• Um redirecionamento de loopback corresponde a qualquer porta. Qualquer outro redirecionamento deve corresponder exatamente.

• Caracteres curinga, fragmentos, credenciais antes do host (user@), barras invertidas, caracteres não ASCII e hosts codificados em porcentagem são recusados.

• O host que um cliente vê na tela de consentimento vem dos seus URIs de redirecionamento ou do seu URL client_id. Registre apenas os hosts que você possui.

Etapa 2: Envie o cliente para Notiondesk

Crie um code_verifier aleatório e, em seguida, derive o code_challenge como o hash SHA-256 do verificador, codificado em base64url ( PKCE ). Redirecione o navegador do cliente para:

https://api.notiondesk.so/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Facme.example%2Foauth%2Fcallback
  &scope=read%20write
  &state=RANDOM_STATE
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.notiondesk.so

• resource é obrigatório e deve ser exatamente https://api.notiondesk.so: minúsculas, sem barra no final, sem caminho. Um valor ausente ou diferente resulta em invalid_request.

• scope é uma lista separada por espaços. Solicite apenas os escopos que seu aplicativo utiliza.

• state protege contra falsificação de solicitação entre sites. Verifique-o quando o cliente retornar.

Um token emitido para a API REST Notiondesk funciona apenas com a API REST. Um token emitido para o Workspace MCP é rejeitado pela API REST, e vice-versa.

Etapa 3: O cliente aprova seu aplicativo

Notiondesk exibe a tela de consentimento. O cliente faz login e vê o nome e o host do seu aplicativo, seu espaço de trabalho e os escopos da sua solicitação que sua função permite. Ele aprova ou nega toda a solicitação.

Os escopos que seu aplicativo pode receber dependem da função do cliente no espaço de trabalho:

admin permite que seu aplicativo altere a identidade visual da central de ajuda, configure integrações cujos scripts são carregados na central de ajuda pública e exclua redirecionamentos. Solicite-o somente se seu aplicativo usar essas rotas.

O cliente não pode aprovar a solicitação quando:

• A função deles não permite nenhuma das atribuições que você solicitou;

• O espaço de trabalho deles não tem acesso à API. A tela de consentimento exibe então a mensagem "O plano do espaço de trabalho não inclui acesso à API". O acesso à API requer um plano Enterprise.

Após a aprovação, o navegador retorna ao seu redirect_uri com um code, seu state e iss, o identificador do servidor de autorização Notiondesk. Se o cliente negar, o redirecionamento carrega error=access_denied em vez disso.

Passo 4: Troque o código por tokens

O código é válido por 60 segundos e funciona apenas uma vez:

Omita client_secret para um cliente público. A resposta:

scope lista os escopos concedidos pelo cliente, que podem ser em número inferior ao solicitado. Armazene ambos os tokens em seu servidor.

Etapa 5: Chame a API Notiondesk

Envie o token de acesso como um token de portador, exatamente como uma chave de API:

Os escopos do token são limitados à função atual do cliente que aprova: um cliente alterado para Visualizador deixa seu aplicativo apenas com read, e uma rota que precisa de um escopo ausente responde 403 insufficient_scope.

Os orçamentos de limite de taxa e os valores Idempotency-Key pertencem à concessão. Cada aprovação é uma nova concessão com seus próprios orçamentos e chaves, e uma atualização de token mantém ambos.

Etapa 6: Atualize o token de acesso.

Um token de acesso tem validade de uma hora. Antes que expire, troque o token de atualização por um novo par:

Cada atualização retorna um novo token de atualização válido por 30 dias e invalida o token enviado anteriormente. Armazene o novo token de atualização antes de usar o novo token de acesso.

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code=THE_CODE \
  -d code_verifier=YOUR_CODE_VERIFIER \
  -d redirect_uri=https://acme.example/oauth/callback

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8f3c...",
  "scope": "read write"
}

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

curl -X POST "https://api.notiondesk.so/oauth/token" \
  -d grant_type=refresh_token \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d refresh_token=THE_REFRESH_TOKEN

Nunca reutilize um token de atualização. Enviar um token que já foi usado revoga toda a concessão, incluindo o token de acesso, pois a reutilização significa que o token foi copiado. O cliente deverá então autorizar seu aplicativo novamente.

Como os clientes revogam a assinatura do seu aplicativo

Os proprietários e administradores do espaço de trabalho visualizam todos os aplicativos com acesso ao seu espaço de trabalho em Configurações > Desenvolvedores > Aplicativos conectados . Os aplicativos que usam a API REST exibem a API REST na coluna Acesso , juntamente com o aplicativo, a pessoa que o autorizou, seus escopos e sua última atividade. A revogação encerra a concessão imediatamente: o token de acesso e o token de atualização param de funcionar na próxima solicitação.

Uma bolsa também termina por si só:

• após 30 dias sem atualização;

• quando seu token de atualização for reutilizado.

Enquanto o cliente que aprova não tiver a função necessária para uma rota, ou o plano de espaço de trabalho não tiver acesso à API, as solicitações serão recusadas. Elas voltarão a funcionar se a função ou o plano forem restaurados antes do término da concessão.

Solução de problemas Notiondesk OAuth

Os endpoints de autorização e token respondem a erros OAuth padrão, não ao envelope de erro da API Notiondesk:

{"error": "invalid_grant", "error_description": "Invalid authorization code."}

O endpoint de autorização exibe esses erros por si só e nunca redireciona uma solicitação inválida para o seu redirect_uri. Um consentimento negado chega ao seu aplicativo apenas como o redirecionamento error=access_denied.

As chamadas à própria API respondem com o envelope de erro da API Notiondesk . Um token de acesso expirado ou revogado responde com o código 401 authentication_error com a mensagem "Chave de API inválida ou ausente.", a mesma mensagem exibida para uma chave de API inutilizável.

Perguntas frequentes

O que vem a seguir?

• Comece a usar a API REST Notiondesk

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

• Desconecte ou revogue o acesso ao Workspace MCP.