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

Cada solicitud a la API de Notiondesk se autentica con un token de portador: una clave API de espacio de trabajo o un token de acceso OAuth para aplicaciones que actúan en nombre de otros clientes de Notiondesk. Este artículo muestra cómo crear una clave API de Notiondesk, elegir sus ámbitos, enviarla con sus solicitudes y rotarla o revocarla.

Utilice una clave API para la automatización que ejecute en su propio espacio de trabajo: un script, una tarea programada, un paso de CI o una herramienta interna. Si está creando una aplicación a la que se conectarán otros clientes de Notiondesk, utilice OAuth en su lugar.

Antes de empezar

• Tu espacio de trabajo está en un plan Enterprise.

• Usted es el propietario del espacio de trabajo o un administrador.

Crea una clave API Notiondesk

1. En tu panel de control de Notiondesk, haz clic en Configuración .

2. En Espacio de trabajo , abre Desarrolladores y luego Claves API .

3. Haz clic en Crear clave .

4. Introduzca una etiqueta que indique para qué sirve la clave, por ejemplo CI automation o Redirect import.

5. En Ámbitos , seleccione solo los ámbitos que necesita la integración. Consulte Elegir los ámbitos correctos .

6. Elija una fecha de vencimiento : 30 días , 90 días , 1 año o Sin vencimiento .

7. Haz clic en Crear .

8. Haz clic en Copiar clave y guarda la clave en tu gestor de secretos o en las variables de entorno.

9. Haz clic en " He guardado la clave" .

La llave se muestra solo una vez. Si la pierdes, gírala para obtener un nuevo secreto.

Nota: Si al crear una clave aparece un candado y la información emergente "Disponible en planes con acceso a la API", su plan no incluye la API. Al hacer clic en ella, se abrirán las opciones de actualización.

Elige los alcances adecuados

Un ámbito es un permiso asociado a una clave. Cada ruta de la API Notiondesk requiere un ámbito, y una clave puede contener varios.

Asigne a cada integración el conjunto mínimo de ámbitos que necesite:

Cómo los roles del espacio de trabajo limitan una clave

Una llave nunca hace más de lo que la persona que la creó puede hacer en tu espacio de trabajo.

Si cambia el rol del creador, los alcances efectivos de la clave cambian con él. Si el creador abandona el espacio de trabajo, la clave deja de funcionar. Gestiona los roles en Cómo invitar a un miembro del equipo .

Envía la clave con cada solicitud.

Envíe la clave en el encabezado Authorization con el esquema Bearer:

Un 200 OK con una lista de tus centros de ayuda confirma que la clave funciona. Una clave funciona para todos los centros de ayuda en su espacio de trabajo.

La misma solicitud en JavaScript:

Y en Python:

Mantén segura tu clave 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()

• Mantén las claves en tu servidor. Nunca coloques una clave en el código del navegador, en una aplicación móvil o en un repositorio público.

• Almacena las claves en variables de entorno o en un gestor de secretos, no en el código fuente.

• Crea una clave por cada integración, con su propia etiqueta, para que puedas revocar una sin afectar a las demás.

• Seleccione una fecha de caducidad para las claves utilizadas por los scripts temporales.

• Cuando alguien que conocía una llave abandona el equipo, debe rotarla.

• Compruebe la columna "Último uso" y revoque las claves que nadie utilice.

Rotar o revocar una clave

Abre Configuración > Desarrolladores > Claves API y usa el menú que aparece al final de la fila de la clave.

La función Rotar reemplaza la clave secreta. Confirme con Rotar : la clave actual deja de funcionar inmediatamente y la nueva se muestra una sola vez. Actualice su integración de inmediato. Una clave caducada no se puede rotar; en su lugar, cree una clave de reemplazo.

Revocar desactiva la clave de forma permanente. Confirmar con Revocar : las automatizaciones que utilizan la clave dejan de funcionar inmediatamente y esta acción no se puede deshacer.

Solución de problemas de autenticación

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

Preguntas frecuentes

¿Qué sigue?

• Comience a usar la API REST Notiondesk

• Conecta tu aplicación a Notiondesk con OAuth.

• Gestionar errores de la API Notiondesk, límites de velocidad y reintentos.