Conecta tu aplicación a Notiondesk con OAuth.

OAuth permite que otros clientes de OAuth conecten tu aplicación a su espacio de trabajo sin compartir una clave API. El cliente inicia sesión en OAuth, revisa lo que solicita tu aplicación y lo aprueba. Tu aplicación recibe un token de acceso para la API REST de OAuth, y el cliente puede revocarlo en cualquier momento. Este artículo describe cómo registrar tu aplicación, ejecutar el flujo de código de autorización OAuth 2.0 con PKCE, actualizar los tokens y gestionar los errores.

Cuándo usar OAuth en lugar de una clave API

Cada ruta de API Notiondesk acepta ambas credenciales y las responde de la misma manera: los mismos ámbitos, respuestas y errores.

Lo que tu aplicación necesita saber

Lea los puntos finales del documento de metadatos del servidor de autorización en lugar de codificarlos directamente.

Ejecuta tu cliente OAuth en un servidor. No se admiten clientes basados ​​en navegador: mantén el intercambio de tokens, los tokens y todas las llamadas a la API en tu servidor backend.

Paso 1: Registra tu aplicación

Regístrese una sola vez con el registro dinámico de clientes :

La respuesta 201 Created contiene su client_id y, dado que solicitó client_secret_post, un client_secret. El secreto se muestra una sola vez: guárdelo con sus otros secretos del servidor.

Con "token_endpoint_auth_method": "none", tu aplicación es un cliente público sin secretos, y PKCE protege su intercambio de código.

En lugar de registrarse, puede usar la URL HTTPS de un documento de metadatos del cliente como su client_id. Notiondesk obtiene el documento cuando un cliente autoriza su aplicación y lo almacena en caché durante un máximo de cinco minutos.

Reglas de redireccionamiento de URI

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"}'

• Utilice https o http en un host de bucle invertido: 127.0.0.1, localhost o [::1].

• Una redirección de bucle invertido coincide en cualquier puerto. Cualquier otra redirección debe coincidir exactamente.

• Se rechazan los caracteres comodín, los fragmentos, las credenciales antes del host (user@), las barras invertidas, los caracteres que no son ASCII y los hosts codificados en porcentaje.

• El host que ve el cliente en la pantalla de consentimiento proviene de tus URI de redireccionamiento o de tu URL client_id. Registra solo los hosts de tu propiedad.

Paso 2: Enviar al cliente a Notiondesk

Cree un code_verifier aleatorio y, a continuación, derive el code_challenge como el hash SHA-256 del verificador, codificado en base64url ( PKCE ). Redirija el navegador del cliente a:

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 es obligatorio y debe ser exactamente https://api.notiondesk.so: en minúsculas, sin barra diagonal final, sin ruta. Un valor faltante o diferente corresponde a invalid_request.

• scope es una lista separada por espacios. Solicita solo los ámbitos que utiliza tu aplicación.

• state protege contra la falsificación de solicitudes entre sitios. Compruébelo cuando el cliente regrese.

Un token emitido para la API REST Notiondesk solo funciona con la API REST. Un token emitido para Workspace MCP es rechazado por la API REST, y viceversa.

Paso 3: El cliente aprueba tu aplicación.

Notiondesk muestra su pantalla de consentimiento. El cliente inicia sesión y ve el nombre y el host de tu aplicación, su espacio de trabajo y los permisos de tu solicitud que su rol le permite. Aprueba o rechaza la solicitud completa.

Los permisos que puede recibir tu aplicación dependen del rol del cliente en el espacio de trabajo:

admin permite que tu aplicación cambie la imagen de marca del centro de ayuda, configure integraciones cuyos scripts se cargan en el centro de ayuda público y elimine redirecciones. Solicítalo solo si tu aplicación utiliza esas rutas.

El cliente no puede aprobar la solicitud cuando:

• Su función no permite ninguno de los ámbitos que usted solicitó;

• Su espacio de trabajo no tiene acceso a la API. La pantalla de consentimiento muestra entonces: "El plan de espacio de trabajo no incluye acceso a la API". El acceso a la API requiere un plan Enterprise.

Tras la aprobación, el navegador regresa a su redirect_uri con un code, su state y iss, el identificador del servidor de autorización Notiondesk. Si el cliente deniega, la redirección lleva error=access_denied en su lugar.

Paso 4: Intercambia el código por tokens

El código es válido durante 60 segundos y funciona una sola vez:

Omita client_secret para un cliente público. La respuesta:

scope enumera los ámbitos que el cliente otorgó, que pueden ser menores que los que usted solicitó. Almacene ambos tokens en su servidor.

Paso 5: Llamar a la API Notiondesk

Envía el token de acceso como un token de portador, exactamente igual que una clave API:

Los alcances del token se limitan al rol actual del cliente que lo aprueba: un cliente que cambia a Viewer deja su aplicación solo con read, y una ruta que necesita un alcance faltante responde 403 insufficient_scope.

Los presupuestos de límite de tasa y los valores Idempotency-Key pertenecen a la subvención. Cada aprobación es una nueva subvención con sus propios presupuestos y claves, y una actualización del token conserva ambos.

Paso 6: Actualizar el token de acceso

Un token de acceso tiene una duración de una hora. Antes de que caduque, intercambie el token de actualización por un nuevo par:

Cada actualización devuelve un nuevo token de actualización válido por 30 días e invalida el que enviaste. Guarda el nuevo token de actualización antes de usar el nuevo token de acceso.

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 reutilices un token de actualización. Enviar uno que ya se haya usado anula la autorización completa, incluido el token de acceso, ya que reutilizarlo implica que el token se copió. El cliente deberá autorizar tu aplicación nuevamente.

Cómo los clientes revocan tu aplicación

Los propietarios y administradores del espacio de trabajo pueden ver todas las aplicaciones con acceso a su espacio de trabajo en Configuración > Desarrolladores > Aplicaciones conectadas . Las aplicaciones que utilizan la API REST muestran "API REST" en la columna Acceso , junto con la aplicación, la persona que la autorizó, sus ámbitos y su última actividad. La revocación finaliza la concesión inmediatamente: su token de acceso y token de actualización dejan de funcionar en la siguiente solicitud.

Una subvención también finaliza por sí sola:

• después de 30 días sin refrescar;

• cuando se reutiliza su token de actualización.

Mientras el cliente que aprueba la solicitud no tenga el rol necesario para la ruta, o el plan del espacio de trabajo no tenga acceso a la API, las solicitudes se rechazan. Se vuelven a procesar si el rol o el plan se restablecen antes de que finalice la concesión.

Solución de problemas de OAuth Notiondesk

Los puntos finales de autorización y token responden a los errores estándar de OAuth, no al sobre de error de la API Notiondesk:

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

El punto final de autorización muestra estos errores por sí mismo y nunca redirige una solicitud no válida a su redirect_uri. Un consentimiento denegado llega a su aplicación únicamente como la redirección error=access_denied.

Las llamadas a la propia API responden con el sobre de error de API Notiondesk . Un token de acceso caducado o revocado responde con el código 401 authentication_error con el mensaje "Clave de API no válida o faltante", el mismo mensaje que recibe una clave de API inutilizable.

Preguntas frecuentes

¿Qué sigue?

• Comience a usar la API REST Notiondesk

• Autentícate con la API Notiondesk usando claves de API.

• Desconectar o revocar el acceso a Workspace MCP