Autenticazione e chiavi API

Come si autentica una chiamata REST?

Invia esattamente una credenziale: Authorization: Bearer seguito da una chiave API o da un token di accesso, oppure x-api-key seguito da una chiave API. Inviarle entrambe, o un’intestazione Authorization con un altro schema, viene rifiutato con HTTP 401.

Che cos’è una chiave API di Fincanva?

• Una chiave inizia con fk_, così una chiave trapelata si riconosce.
• Un account può avere al massimo 10 chiavi alla volta.
• Una chiave non ha una data di scadenza.
• Una chiave funziona solo via REST: il server MCP la rifiuta.
• Le chiavi si creano in «Impostazioni › API», con ogni piano a pagamento: dai un nome alla chiave e premi «Crea chiave».
• La chiave completa compare una sola volta, sotto «Non la vedrai più»: Fincanva ne conserva solo un’impronta.
• «Rinomina» cambia il nome di una chiave; «Revoca» la fa smettere di funzionare subito.

Come funziona OAuth con Fincanva?

Un token di accesso OAuth 2.1 porta lo scope fincanva.research ed è emesso per una sola superficie, REST o MCP, dove funziona. Un client trova dove accedere dai documenti di discovery:

• i metadati della risorsa protetta, in https://app.fincanva.com/.well-known/oauth-protected-resource;
• i metadati dell’authorization server, in https://app.fincanva.com/.well-known/oauth-authorization-server.

Che cosa succede quando l’autenticazione fallisce?

Una credenziale mancante, non valida, scaduta o revocata riceve HTTP 401 unauthorized, e ogni risposta di questo tipo porta un’intestazione WWW-Authenticate che dice che cosa inviare. Un piano che non include la superficie riceve HTTP 403 plan_limit, e details.unlockedBy indica il piano più basso che la include; Piani, quote e limiti mostra quali piani includono ciascuna superficie.