> This page is for Piattaforma, version Versione precedente.
> For other versions, use one of these documentation indexes:
> - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt
> - V4 sperimentale: https://next.developer.frame.io/platform/v4-experimental/llms.txt
> - Versione precedente: https://next.developer.frame.io/platform/v2/llms.txt
> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.
# Guida pratica: Gestire l'autenticazione (hardware)
## Introduzione
In questa guida imparerai come aggiornare, revocare e archiviare le informazioni di autorizzazione del *dispositivo hardware* per Frame.io.
## Cosa serve?
Se non hai letto la guida [Implementazione C2C: configurazione](/camera-to-cloud/implementing-c2c-setting-up), dalle un'occhiata veloce prima di continuare! Ti servono il `client_secret` fornito dal nostro team e lo stesso `client_id` utilizzato nella [guida all'autenticazione e all'autorizzazione](/platform/v2/implementing-c2c-authentication-and-authorization-hardware). Per completare questa guida, sono necessari anche l'`access_token` e il `refresh_token`.
## Token di autorizzazione
Nell'[ultima guida](/platform/v2/implementing-c2c-authentication-and-authorization-hardware) abbiamo imparato a *generare* nuovi token di autorizzazione facendo autenticare e autorizzare l'utente su un dispositivo in un progetto. *I token di accesso durano solo 8 ore circa prima di scadere*. Non vogliamo che l'utente di un dispositivo sia costretto ad associare il dispositivo ogni 8 ore, quindi nell'ultima guida abbiamo richiesto l'ambito `offline` e abbiamo ottenuto anche un *token di aggiornamento* durante l'autorizzazione con Frame.io. I token di aggiornamento possono essere utilizzati per generare un nuovo token di accesso quando quello attuale scade.
*Un token di aggiornamento è valido per 14 giorni*. Limitando il tempo di validità di un access_token, riduciamo i potenziali problemi che potrebbero verificarsi se ne venisse divulgato uno. Se l'autorizzazione non viene aggiornata prima dell'utilizzo del *token di aggiornamento*, l'utente dovrà autenticarsi nuovamente.
## Aggiornamento del token di accesso
Se invii all'API una chiamata che richiede un token di accesso e ricevi la seguente risposta:
```json
{
"code": 401,
"errors": [
{
"code": 401,
"detail": "You are not allowed to access that resource",
"status": 401,
"title": "Not Authorized"
}
],
"message": "Not Authorized"
}
```
..., il token di accesso è scaduto.
Per aggiornare il token, effettua la seguente chiamata:
```shell
curl -X POST https://api.frame.io/v2/auth/token \
--header 'x-client-version: 2.0.0' \
--form 'client_id=[client_id]' \
--form 'client_secret=[client_secret]' \
--form 'grant_type=refresh_token' \
--form 'refresh_token=[refresh_token]' \
| python -m json.tool
```
I documenti per `/v2/auth/token` li [trovi qui](/camera-to-cloud/api-reference/authentication/auth-device-token)
Tutti sono stati generati nella [guida precedente](/platform/v2/implementing-c2c-authentication-and-authorization-hardware). Dagli un'occhiata se non l'hai già fatto, poi torna qui!
Utilizzando tutti questi valori (invece del token di aggiornamento da solo), è possibile generare una nuova autorizzazione da un token di aggiornamento divulgato online. Se qualcuno vuole generare un token come se fosse la tua integrazione, avrà bisogno del `refresh_token` e *anche* del `client_secret`.
Dovresti ricevere una risposta simile a questa:
```json
{
"access_token": "[access_token]",
"expires_in": 28800,
"refresh_token": "[refresh_token]",
"token_type": "bearer"
}
```
Questi sono i tuoi nuovi token di autorizzazione. *Una volta aggiornati i token, quelli precedenti non funzioneranno più*, quindi tienili sempre a portata di mano!
Se proviamo a utilizzare il vecchio token di aggiornamento per eseguire subito l'aggiornamento, riceveremo un errore:
```json
{
"error": "invalid_request"
}
```
Il token è già stato aggiornato, quindi l'utilizzo del token di aggiornamento esistente non è valido.
Se ricevi una risposta `401 Not Authorized` durante l'aggiornamento dei token, significa che il token non è più valido e dovrai riavviare nuovamente il processo di autorizzazione.
## Risposta di aggiornamento mancante
I valori di `refresh_token` possono essere utilizzati una sola volta. Se effettui una chiamata a Frame.io per aggiornare un token e non ricevi la risposta a causa di un errore di rete o di un'interruzione imprevista dell'alimentazione, *dovrai riavviare l'intero flusso di autenticazione e autorizzazione.*
Si tratta di un evento sfortunato, ma è meglio essere prudenti!
## Revoca dei token
In alcuni casi, potresti voler "uscire" da Frame.io. Un utente potrebbe decidere di non voler più essere connesso dopo aver completato una ripresa, ad esempio. Revocare l'autorizzazione è anche una buona prassi se l'app entra in uno stato di errore e deve essere ripristinata. Ogni volta che sai prevedi di eliminare l'autorizzazione corrente, la app dovrebbe tentare di revocarla.
Per revocare l'autorizzazione, effettua la seguente chiamata:
Dopo aver effettuato questa chiamata, dovrai riavviare il processo di autenticazione e autorizzazione descritto [nell'ultima guida](/platform/v2/implementing-c2c-authentication-and-authorization-hardware).
```shell
curl -X POST https://api.frame.io/v2/auth/revoke \
--include \
--header 'x-client-version: 2.0.0' \
--form 'client_id=[client_id]' \
--form 'client_secret=[client_secret]' \
--form 'token=[refresh_token]
```
I documenti per `/v2/auth/revoke` li [trovi qui](/camera-to-cloud/api-reference/authentication/auth-device-revoke-token)
La risposta non conterrà un payload. Abbiamo utilizzato `--include` nel comando per stampare le intestazioni restituite, che dovrebbero iniziare con un codice di stato `200` se la chiamata è riuscita:
```text
HTTP/2 200
...
```
Ora che il token è stato revocato, tutte le chiamate a [Frame.io](http://frame.io/) che richiedono un `access_token` restituiranno `Not Authorized`. Se l'utente desidera utilizzare nuovamente la connessione Frame.io, dovrà associare di nuovo il dispositivo al progetto.
## Archiviazione dei token
Per mantenere la funzionalità durante i cicli di potenza, dovrai archiviare le intestazioni di autorizzazione inattive.Questo può essere fatto in un file, un database o nel tuo cloud.Ecco alcune linee guida per archiviare i token di autorizzazione:
**Non permettere all'utente di vedere o accedere ai token**.L'utente non deve mai poter visualizzare o recuperare i token.Devono essere gestiti dalla tua applicazione e solo da quella.**Crittografa i token at rest.**Come per il `client_secret`, i token di accesso e aggiornamento devono essere crittografati at rest quando è possibile, in modo da evitare il furto delle chiavi.*Le chiavi di autorizzazione non devono essere archiviate in testo normale.* **Non archiviare i token di autorizzazione nello stesso file del client_secret.**L'applicazione Python di esempio archivia il `client_secret` e il `client_id` nello stesso file dei token di autorizzazione.Va bene per una demo, ma non è una buona pratica per il codice di produzione.`client_secret` e `client_id` sono valori statici per un dispositivo, e *il dispositivo smetterà di funzionare se vengono persi.* I token di autorizzazione non sono statici e dovranno essere riscritti molte volte durante la vita del dispositivo.Se il dispositivo dovesse perdere potenza durante l'aggiornamento di un file con nuovi token, quel file potrebbe corrompersi e il `client_secret` potrebbe andare perso, impedendo al dispositivo di riautenticarsi su Frame.io *per sempre*.Separando i token, nel peggiore dei casi un utente dovrà associare di nuovo il dispositivo.
Il posto migliore per archiviare i token è un database comprovato come SQLite, ma come minimo i dati di autorizzazione devono essere separati dagli altri valori.
## Avanti
Se non l'hai già fatto, ti incoraggiamo a contattare il nostro team, poi continua con la prossima guida.A presto!