> This page is for Da videocamera a cloud.
> 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'autorizzazione
## Panoramica
Questa guida descrive le procedure per gestire i token di autorizzazione del dispositivo in Frame.io, inclusi aggiornamento, revoca e procedure di archiviazione sicura dei token.
## Prerequisiti
Rivedi la guida [Implementazione C2C: configurazione](./implementing-c2c-setting-up) per assicurarti che la configurazione sia corretta.
Componenti essenziali richiesti:
* Un `client_secret` valido rilasciato da Frame.io
* Il `client_id` che ti è stato assegnato, come descritto nella [guida di autenticazione e autorizzazione](./implementing-c2c-authentication-and-authorization)
* Credenziali `access_token` e `refresh_token` valide
## Informazioni sui token di autorizzazione
La guida precedente sull'[autenticazione del dispositivo](./implementing-c2c-authentication-and-authorization) ha spiegato il processo per ottenere i token di autorizzazione iniziali tramite l'autenticazione dell'utente. I token di accesso funzionano per circa 8 ore. Per eliminare la necessità associare frequentemente il dispositivo, implementiamo l'ambito `offline` per ottenere un token di aggiornamento insieme all'autorizzazione. Questo token di aggiornamento consente di generare nuovi token di accesso alla scadenza.
I token di aggiornamento hanno una validità di 14 giorni. Questa limitazione deliberata per la durata dei token di accesso migliora la sicurezza e riduce le potenziali vulnerabilità dai token compromessi. Tieni presente che se l'autorizzazione non viene rinnovata prima della scadenza del token di aggiornamento, l'utente deve autenticarsi di nuovo.
## Processo di rinnovo del token di accesso
Alla scadenza del token di accesso, le richieste API riceveranno questa risposta:
```json
{
"code": 401,
"errors": [
{
"code": 401,
"detail": "You are not allowed to access that resource",
"status": 401,
"title": "Not Authorized"
}
],
"message": "Not Authorized"
}
```
Esegui questo comando per ottenere un nuovo token:
```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
```
La documentazione dettagliata per `/v2/auth/token` è disponibile [qui](/camera-to-cloud/api-reference/authentication/auth-device-token)
Questa implementazione richiede più fattori di autenticazione per migliorare la sicurezza. Una parte non autorizzata dovrebbe ottenere sia il `refresh_token` che il `client_secret` per impersonare con successo la tua integrazione.
Se il rinnovo riesce, viene generata questa risposta:
```json
{
"access_token": "[access_token]",
"expires_in": 28800,
"refresh_token": "[refresh_token]",
"token_type": "bearer"
}
```
Al completamento dell'aggiornamento del token, le credenziali precedenti diventano non valide. Assicurati di conservare in modo adeguato i nuovi token di autorizzazione.
Se si tenta di riutilizzare un token di aggiornamento, compare questo messaggio:
```json
{
"error": "invalid_request"
}
```
Questo indica che il token è stato elaborato in precedenza e non è più valido.
La ricezione di una risposta `401 Not Authorized` durante l'aggiornamento del token indica che le credenziali non sono più valide, perciò è necessario un nuovo processo di autorizzazione.
## Gestione delle risposte di aggiornamento non riuscite
Poiché i valori di `refresh_token` possono essere usati una sola volta, la mancata acquisizione della risposta di aggiornamento (sia in caso di interruzione di rete che in caso di arresto del sistema) rende necessario riavviare l'intera sequenza di autenticazione e autorizzazione.
Questo protocollo di sicurezza, seppur potenzialmente scomodo, è essenziale per mantenere l'integrità del sistema.
## Processo di revoca del token
In alcune circostanze, potrebbe essere necessario chiudere l'accesso a Frame.io, ad esempio in caso di completamento del progetto o reimpostazione dell'app. Implementa le procedure di revoca appropriate quando annulli l'autorizzazione corrente.
Esegui il comando seguente per revocare l'autorizzazione:
Dopo la revoca, devi riavviare il processo di autenticazione e autorizzazione come descritto nella [guida di autenticazione e autorizzazione](./implementing-c2c-authentication-and-authorization).
```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]'
```
La documentazione completa per `/v2/auth/revoke` è disponibile [qui](/camera-to-cloud/api-reference/authentication/auth-device-revoke-token)
Il sistema restituisce intestazioni senza payload. La riuscita dell'operazione è indicata da un codice di stato `200`:
```text
HTTP/2 200
...
```
Dopo la revoca, le operazioni Frame.io che richiedono l'autenticazione mediante `access_token` restituiranno `Not Authorized`. Il ripristino dell'accesso richiede la riassociazione del dispositivo al progetto.
## Implementazione dell'archiviazione dei token
Per mantenere persistente l'autorizzazione tra i vari riavvii del sistema, è necessaria l'archiviazione sicura dei token. Segui queste linee guida di base:
**Implementa i controlli di accesso degli utenti:** limita la visibilità e l'accesso ai token esclusivamente ai processi dell'app. **Abilita la crittografia dell'archiviazione:** implementa la crittografia per i token archiviati, inclusi il `client_secret` e le credenziali di autorizzazione. Non mantenere mai le chiavi di autorizzazione in formato di testo normale. **Separa le credenziali:** l'app Python di esempio consolida l'archiviazione, ma gli ambienti di produzione dovrebbero separare i token di autorizzazione dal `client_secret`. Considera questi fattori:
* `client_secret` e `client_id` rappresentano credenziali permanenti del dispositivo: se vengono perse, il dispositivo non funzionerà più
* I token di autorizzazione vengono aggiornati regolarmente durante il funzionamento del dispositivo
* L'archiviazione segregata assicura che la corruzione dell'archiviazione dei token richieda solo la riassociazione del dispositivo, invece della reimpostazione completa dell'autenticazione
Anche se SQLite offre capacità ottimali per l'archiviazione dei token, implementa almeno un'archiviazione separata per i dati di autorizzazione e le credenziali principali.
## Passaggi successivi
Seguiamo i tuoi progressi e ti invitiamo a passare alla [guida per lo stato di connessione e gli heartbeat](./how-to-heartbeats-connection-info-and-status). Contatta il nostro team per qualsiasi domanda o problema.