Autenticación

Clientes

• Solo el titular de la cuenta puede crear un cliente, y solo en la app de Novo, después de un paso de verificación. La misma verificación se aplica cuando un cliente se rota o se reactiva.
• Un negocio por cliente. Un cliente está vinculado al titular y a un negocio. No puede acceder a ningún otro negocio.
• El secret se muestra una sola vez. Novo solo guarda un hash. Guárdalo como una contraseña y envíalo solo al endpoint de tokens, nunca en una llamada a la API.
• Los secrets vencen, tanto después de un periodo fijo como después de un periodo sin uso. Los periodos son propuesto y pueden cambiar durante la beta.

Scopes

El titular elige los scopes de un cliente al crearlo. Son fijos durante toda la vida del cliente: para cambiarlos, crea un cliente nuevo. Todo lo que un scope no permite se rechaza.

accounts:read

Saldos y datos de la cuenta, con los números ocultos salvo los últimos 4 dígitos

transactions:read

Transacciones registradas, pendientes y de tarjeta

bookkeeping:read

Transacciones de contabilidad

cards:read

Lista de tarjetas con los últimos 4 dígitos y su estado

cards:freeze

Congelar una tarjeta. Solo congelar: descongelar se queda en la app de Novo

Tokens de acceso

Cambia el client id y el secret en /v1/oauth/token con grant_type=client_credentials. HTTP Basic es lo predeterminado; enviar ambos como campos de formulario también funciona.

curl -X POST "https://$NOVO_API_HOST/v1/oauth/token" \
  -u "nvo_client_example:$CLIENT_SECRET" \
  -d "grant_type=client_credentials"

• El token es opaco: no es un JWT, así que no intentes decodificarlo.
• Dura expires_in segundos: 900, es decir, 15 minutos propuesto. Guárdalo en caché y reutilízalo hasta entonces. Cuando una llamada devuelva token-expired, pide uno nuevo.
• Lleva los scopes del cliente. El campo scope de la solicitud está reservado y se ignora.
• Envíalo como Authorization: Bearer <token>.

El endpoint de tokens responde con errores de OAuth 2.0 en lugar de problem details: uno de invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope. Cualquier problema con el propio cliente recibe la misma respuesta invalid_client, sea cual sea la causa.

Revocación

El titular puede revocar un cliente en la app de Novo en cualquier momento. La revocación surte efecto en 30 segundos propuesto, más cualquier llamada que ya esté en curso. Un cliente revocado o suspendido, o uno que Novo desactivó, recibe 401 client-disabled.

Si el titular al que está vinculado este cliente pierde el rol de titular, o su perfil se bloquea o deja de estar en regla, las llamadas se detienen. Primero recibes 403 owner-standing-lost; una vez revocado el cliente, 401 client-disabled. Un titular actual crea un cliente nuevo en la app.

Dar acceso a un agente de IA

Guarda el client secret en tu gestor de secretos y úsalo solo para llamar al endpoint de tokens. El agente recibe el token de acceso de corta duración, nunca el secret: un token filtrado son, como mucho, 15 minutos de los scopes del cliente, mientras que un secret filtrado es el cliente entero hasta que lo rotes propuesto. Dale al agente un cliente con solo los scopes que necesita: un cliente sin cards:freeze solo puede leer. Consulta texto no confiable para ver qué no debe tomar nunca un agente como una instrucción.

Limitar una clave a donde se ejecuta Previsto

Puedes limitar una clave a las herramientas y equipos que aprobaste. Si se usa desde cualquier otro lugar, se detiene y espera tu sí en la app de Novo.

Tu integración guarda un par de claves donde se ejecuta y firma cada solicitud con él (OAuth 2.0 DPoP, RFC 9449). Novo nunca ve la clave privada; tu herramienta solo envía la clave pública. Una vez limitada la clave, un client secret o un token de acceso robado no consigue nada por sí solo. Un cliente limitado recibe token_type DPoP en lugar de Bearer, y envía una prueba nueva con cada solicitud.

• Empareja la primera instalación poco después de crear la clave (en 15 minutos) confirmando en la app de Novo un código corto que muestra tu herramienta.
• Una solicitud desde cualquier otra instalación queda retenida, de una en una, durante 15 minutos hasta que la apruebes en la app. Si la rechazas, también puedes revocar la clave.
• Elimina una instalación en la app y sus tokens dejan de funcionar en unos 30 segundos.
• La API no puede distinguir las apps por su nombre. Dale a cada herramienta su propio cliente con solo los scopes que necesita, y limita cada uno a donde se ejecuta.
• Para limitarla, tu herramienta tiene que guardar un par de claves donde se ejecuta. Un servicio alojado que no pueda hacerlo no se puede limitar; dale su propio cliente con solo los scopes que necesita.

Lo que no impide:

• Que alguien se lleve el client secret y la clave privada del mismo equipo. Esa persona es el cliente hasta que elimines ese origen en la app.
• Que un proceso comprometido o con prompt injection use la clave donde está. Ahí la protección son los scopes y la aprobación de cada acción.