Autenticación
API keys con esquema Bearer, prefijos por entorno, scopes y rotación.
Todas las requests a la API de Notta se autentican con un API key en el
header Authorization, usando el esquema Bearer:
No hay sesiones ni OAuth para la API: el key es la credencial. Trátalo como una contraseña: quien lo tenga puede emitir DTEs en nombre de tu organización.
Entornos: cert y producción
Cada key está vinculada a un entorno SII. El prefijo del key determina a qué entorno van tus emisiones:
| Prefijo | Entorno | Estado |
|---|---|---|
ntt_cert_… | Cert / sandbox (maullin.sii.cl) | Disponible desde el día 1, sin tarjeta |
ntt_prod_… | Producción (palena.sii.cl) | Requiere certificación SII como emisor electrónico |
Un key ntt_cert_ siempre va a maullin (sandbox, sin valor tributario).
Un key ntt_prod_ siempre va a palena (valor tributario real).
El entorno es fijo por key: no depende de la configuración de tu org.
Keys anteriores con prefijo rk_test_
Las keys creadas antes del rediseño de prefijos empiezan con rk_test_ y siguen
funcionando igual: apuntan a cert (maullin). No necesitas rotar tus keys
existentes por este cambio.
El prefijo también le dice el entorno a cualquier cliente que uses: no hace falta configurarlo aparte.
Obtener y rotar keys
- Crear: crea una key directo en el dashboard. El secreto se muestra una sola vez; guárdalo en tu gestor de secretos.
- Scopes: cada key se limita a scopes. Los de DTE son
dte:readydte:write(ydte:emit). Un request que requiere un scope que el key no tiene responde403 forbidden, con unhintque indica el scope faltante (p. ej.dte:write). - Rotar: genera un key nuevo, despliégalo, y recién después revoca el viejo. La revocación es inmediata.
Errores de autenticación
| Código | HTTP | Cuándo | next_action |
|---|---|---|---|
unauthorized | 401 | Falta el header Authorization: Bearer | send_bearer_token |
invalid_api_key | 401 | Key inválida (no matchea) | regenerate_api_key |
api_key_revoked | 401 | Key revocada | regenerate_api_key |
api_key_expired | 401 | Key expirada | regenerate_api_key |
forbidden | 403 | Key sin el scope requerido | use_api_key_with_required_scope |
El catálogo completo está en Errores.
Nunca publiques un key
No pongas un key en código cliente, repos ni logs. Si se filtra, revócalo de inmediato desde el dashboard.
Próximos pasos
- Tu primer DTE: usa tu key recién creada para emitir una Factura 33 en sandbox.
- Errores: catálogo completo con
next_actionpor código. - Rate limits: cuotas por key y cómo leer los headers de límite.
- Servidor MCP: conecta tu agente por OAuth sin instalar nada (no acepta tu API key). Sus permisos los concede un humano en la pantalla de consentimiento, y la escritura la gobierna el techo de tu empresa.
Última actualización