# Opzioni di autenticazione dell'agente

Collegare con una chiave API o MCP OAuth, verificare l'accesso senza una query a pagamento e riutilizzarlo per le attività successive.

Riferimento canonico: https://flashdata.dev/it/docs/guides/agent-access
Recensito: 2026-11-05 da FlashData

<a id="access"></a>

## 1. Scegliere e connettersi

Sei già connesso? Go direttamente al check-in gratuito 2. In caso contrario, scegliere l'accesso alle esigenze dell'applicazione o dell'agente.

| Tu stai collegando | Uso | Chi tiene le credenziali? |
| --- | --- | --- |
| Un'applicazione, SDK, CLI o script programmato | Proprietario chiave API | Il negozio segreto del server o il profilo CLI |
| Strumenti di ricerca Codex o OpenClaw | MCP OAuth | L'host dopo il consenso del browser |
| Un agente che prova FlashData senza un account | Chiave temporanea API | Il profilo di prova salvato dell'agente, quindi l'accesso del proprietario dopo aver reclamato |

### Chiave API

Creare una chiave in API Keys con le fonti di cui hai bisogno, o riutilizzare una chiave esistente. Forniscilo al tuo SDK o invialo come X-API-Key dal tuo backend. Gli assegni Bash e PowerShell nel passaggio 2 funzionano direttamente con API; non è richiesta alcuna installazione CLI.

- [API Keys](https://flashdata.dev/app/api-keys)
- [Salvare una chiave nella CLI](https://flashdata.dev/it/docs/guides/agent-access/reference.md#import-key)
- [Configurazione chiave SDK e HTTP](https://flashdata.dev/it/docs/guides/api-keys-and-permissions/reference.md#store)

### MCP OAuth

Utilizzare un host configurato per FlashData OAuth. Il proprietario dell'account completa l'iscrizione o l'accesso e il consenso nel browser; l'host salva i gettoni. Questa connessione non installa una chiave CLI o richiede una prova.

#### Collegamento hostato MCP

```text
URL: https://data.flashdata.dev/mcp
Transport: Streamable HTTP
Authentication: OAuth
Scope: mcp:research
```

- [Collegare Codex](https://flashdata.dev/it/docs/integrations/codex/reference.md#setup)
- [Collegare OpenClaw](https://flashdata.dev/it/docs/integrations/openclaw/reference.md#setup)
- [Altri client MCP](https://flashdata.dev/it/docs/integrations/mcp-clients/reference.md#connect)

### prova agente

Per un agente senza chiave, discover l'attuale eleggibilità di prova prima di registrarsi. Riutilizzare una prova esistente e il suo profilo. YouTube Le attività di download e di ricorsi richiedono l'accesso del proprietario.

#### Scoprire senza registrarsi

```bash
flashdata discover --profile research --json
```

- [Avviare una prova e rivendicarlo](https://flashdata.dev/it/docs/guides/agent-onboarding/reference.md)
- [Protocollo di autenticazione agente](https://flashdata.dev/auth.md)


<a id="permissions"></a>

### Quali fonti possono usare queste credenziali?

Utilizzare X-API-Key per normali richieste HTTP e connessioni API-chiave MCP. I gettoni portanti OAuth funzionano solo all'endpoint MCP ospitato. YouTube Download ha bisogno di una chiave API con youtube_download e storage di destinazione.

| Credenziali | Fonti disponibili |
| --- | --- |
| Proprietario chiave API | Le fonti concesse alla chiave, incluso youtube_download quando approvato. |
| Chiave temporanea API | Solo fonti di prova eleggibili. Leggi gli ambiti della risposta dell'identità corrente. |
| MCP OAuth | google_search, youtube_search, youtube_metadata, youtube_transcript |


<a id="import-key"></a>

### Salvare una chiave nella CLI

Salta l'importazione se CLI ha già accesso o il tuo manager segreto fornisce FLASHDATA_API_KEY. In caso contrario, scegliere un metodo qui sotto e mantenere lo stesso profilo di ricerca per i comandi successivi. Una chiave CLI salvata non è automaticamente disponibile per i server SDK o MCP locali.

#### Terminale interattivo

Incolla la chiave al prompt dei terminali nascosti.

##### Importare una volta

```bash
flashdata auth login --profile research
```


#### Automazione · Bash

Impostare FLASHDATA_KEY_FILE sul percorso di un file chiave protetto esistente. Il comando lo legge tramite stdin; tieni la chiave fuori dalla chat e dagli argomenti di comando.

##### Leggi un segreto protetto tramite stdin

```bash
: "${FLASHDATA_KEY_FILE:?Set the path to your protected API-key file}"
flashdata auth login --profile research --api-key-stdin --non-interactive \
  < "$FLASHDATA_KEY_FILE"
```


- [Installazione CLI](https://flashdata.dev/it/docs/guides/flashdata-cli/reference.md#install)

<a id="verify"></a>

## 2. Verificare la connessione

Eseguire il controllo gratuito nell'ambiente che eseguirà l'attività. I controlli CLI e HTTP utilizzano una chiave API; il controllo MCP utilizza la connessione salvata dell'host.

### Bash / cURL

Richiede Bash e cURL 7.76+. Salta il prompt dei tasti nascosti se il tuo ambiente già fornisce FLASHDATA_API_KEY. Eseguire i comandi di lettura nello stesso terminale.

#### Impostare la chiave · saltare se già configurato

```bash
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
```

#### Leggi l'account JSON

```bash
(
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
curl --fail-with-body --silent --show-error --max-time 20 \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  'https://api.flashdata.dev/v2/api-access/identity' || exit
printf '\n'
)
```


### PowerShell 7

Salta il prompt dei tasti nascosti se FLASHDATA_API_KEY è già impostato. Eseguire i comandi di lettura nello stesso terminale.

#### Impostare la chiave · saltare se già configurato

```powershell
# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey
```

#### Leggi l'account JSON

```powershell
& {
  $ErrorActionPreference = 'Stop'
  if ([string]::IsNullOrWhiteSpace($env:FLASHDATA_API_KEY)) {
    throw 'Set FLASHDATA_API_KEY first'
  }
  $flashdataHeaders = @{ 'X-API-Key' = $env:FLASHDATA_API_KEY }
  $flashdataBase = 'https://api.flashdata.dev/v2'
  $flashdataUri = "$flashdataBase/api-access/identity"
  Invoke-RestMethod -Uri $flashdataUri `
    -Headers $flashdataHeaders -TimeoutSec 20 -MaximumRedirection 0 |
    ConvertTo-Json -Depth 20
}
```


### CLI

Utilizzare la directory utente, profilo e stato OS dal login. Sostituire la ricerca se si utilizza un altro profilo; aggiungere --state-dir PATH se necessario. FLASHDATA_API_KEY sovrascrive la chiave salvata. Aspettatevi ok: true e data.accessVerified: true; poi ispeziona i campi di identità qui sotto.

#### Leggi di account gratuito

```bash
flashdata auth status --profile research --json --non-interactive
```

- [Impostare una chiave](https://flashdata.dev/it/docs/guides/api-keys-and-permissions/reference.md#store)

### MCP

Invia questo ad una sessione nuova del tuo agente connesso. Sostituisci google_search con la fonte di cui hai bisogno. Aspettatevi che entrambe le chiamate degli strumenti per avere successo; controllare i prezzi e l'equilibrio separatamente prima del lavoro pagato. Un server elencato da solo non verifica l'accesso.

#### Controllo della connessione

```text
Utilizzare la connessione flashdata esistente MCP.
Chiama get_pricing con {"source":"google_search","request_count":1}.
Chiama get_balance con {}.
Se entrambe le chiamate sono succedute, se la fonte ha un prezzo disponibile,
e il saldo di credito disponibile. Un saldo zero non è un guasto di autenticazione.
Non eseguire una ricerca o scaricare, creare una prova, o modificare le credenziali.
```



<a id="identity-result"></a>

### Leggi l'identità API-chiave

I campi di identità HTTP sono al livello superiore. In CLI JSON, leggere data.identity.identity e richiedere data.accessVerified: true. HTTP 200 o CLI ok: true da solo non è sufficiente.

| Check | Risultato richiesto |
| --- | --- |
| Conto intenso | accountId e apiKeyId identificano l'account e la chiave che si intende utilizzare. |
| Accesso utilizzabile | access: ready |
| Permesso di attività | gli ambiti contengono la fonte, come google_search. CLI elenca anche le fonti consentite in data.identity.permittedSources. |
| Attività ricorrente | accountType: owned · installed: true · recurringAllowed: true |

- [Automatizzare questi controlli prima della pianificazione](https://flashdata.dev/it/docs/guides/agent-access/reference.md#recurring-check)

<a id="trial-result"></a>

### Una prova attiva è una connessione valida

Una prova può passare un controllo di attività uno-off mentre recurringAllowed è false. Leggere gli scopi e la scadenza effettivi; rivendicare il prova esistente prima della programmazione.

#### Identità temporanea · campi illustrativi

```json
{
  "accountType": "temporary",
  "access": "ready",
  "installed": false,
  "recurringAllowed": false,
  "scopes": [
    "google_search"
  ]
}
```


<a id="codex"></a>

### Trova la connessione in Codex

Elenca i server configurati, quindi usa /mcp in una sessione Codex fresca. Eseguire il controllo MCP sopra per verificare le credenziali.

#### Elenco dei server

```bash
codex mcp list
```

- [Configurazione Codex e prima attività](https://flashdata.dev/it/docs/integrations/codex/reference.md)

<a id="openclaw"></a>

### Controllare la connessione in OpenClaw

Sondare il server salvato, quindi eseguire il controllo MCP sopra nella conversazione attiva.

#### Sonda il server

```bash
openclaw mcp doctor flashdata --probe
```

- [Configurazione OpenClaw e prima attività](https://flashdata.dev/it/docs/integrations/openclaw/reference.md)

<a id="refresh"></a>

## 3. Riutilizzare l'accesso per le attività successive

Mantenere il negozio di credenziali privato e persistente attraverso riavviamenti di processo. Ricontrollare l'accesso in un processo fresco prima di abilitare il programmatore.

| Credenziali | Per il prossimo compito |
| --- | --- |
| Proprietario chiave API | Riutilizzare la chiave salvata. Non ha alcun passo di aggiornamento OAuth; sostituirlo se scaduto o revocato. |
| MCP OAuth | L'host aggiorna i token di accesso OAuth di un'ora utilizzando token di aggiornamento rotanti. Ricollegare quando la sovvenzione 90-day scade o viene revocata. Ogni installazione possiede il suo negozio di token; non condividere i file di aggiornamento-token tra gli host. |
| Chiave temporanea API | Terminare il proprietario che reclama e le credenziali di consegna prima del lavoro ricorrente. Riutilizzare il profilo originale; non registrarsi di nuovo per ogni corsa. |

- [Flusso di lavoro dell'attività ricorrente](https://flashdata.dev/it/docs/guides/recurring-tasks/reference.md)

<a id="recurring-check"></a>

### Controllare un'attività CLI prima della pianificazione

Richiede Bash e jq. Impostare la FONTE alla fonte del compito. Lo script utilizza la ricerca per impostazione predefinita; impostare FLASHDATA_PROFILE e FLASHDATA_STATE_DIR per una directory diversa o di stato. Uscita 0 con identità JSON significa che la chiave del proprietario è pronta, installata e consentita per questa fonte. Fai smettere il programmatore su qualsiasi altra uscita. Nessuna domanda è presentata.

#### Controllo dell'accesso al processo fresco · Bash

```bash
(
set -euo pipefail
SOURCE=google_search
args=(--profile "${FLASHDATA_PROFILE:-research}" --json --non-interactive)
if [[ -n "${FLASHDATA_STATE_DIR:-}" ]]; then
  args+=(--state-dir "$FLASHDATA_STATE_DIR")
fi

flashdata auth status "${args[@]}" |
  jq -e --arg source "$SOURCE" '
    select(.ok == true and .data.accessVerified == true)
    | .data.identity as $auth
    | $auth.identity
    | select(.accountType == "owned" and .access == "ready"
        and .installed == true and .recurringAllowed == true
        and ((.scopes // []) | index($source) != null)
        and (($auth.permittedSources // []) | index($source) != null))
    | {accountId, apiKeyId, scopes, recurringAllowed, expiresAt}'
)
```

- [Aggiungere i prezzi, l'equilibrio e un corridore ricorrente](https://flashdata.dev/it/docs/guides/recurring-tasks/reference.md#prepare)

<a id="claim"></a>

### Se l'accesso è ancora una prova

Completare la guida di prova e rivendicazione con il profilo originale. Dopo l'approvazione del proprietario e la consegna delle credenziali, il controllo gratuito dovrebbe mostrare l'accesso di proprietà e recurringAllowed: true. Le richieste continue utilizzano il saldo condiviso del proprietario; i crediti di prova non utilizzati non trasferiscono. MCP OAuth login è una connessione separata e non richiede questo prova.

- [Comandi di prova e di reclamo](https://flashdata.dev/it/docs/guides/agent-onboarding/reference.md)
- [auth.md](https://flashdata.dev/auth.md)

<a id="revoke"></a>

## Accesso di fatturazione

Pausa che si occupa prima di tutto. Rivolgere le credenziali corrispondenti di seguito, quindi ripetere il controllo gratuito da un processo fresco o sessione prima di cancellare l'accesso locale. Aspettatevi un guasto dell'autenticazione o una richiesta di ricollegamento; non approvate una nuova connessione durante il controllo. Il logout locale non revoca l'accesso al server.

| Connessione | Dove revocare |
| --- | --- |
| MCP OAuth | Settings → Connected apps → sovvenzione dell'app. |
| Chiave dell'agente API | Settings → Connected apps → Collegamenti agente. |
| Account chiave API | API Keys → la chiave utilizzata da questa integrazione. |

- [Connected apps](https://flashdata.dev/app/settings/connections)
- [API Keys](https://flashdata.dev/app/api-keys)
- [Risoluzione problemi errori di accesso](https://flashdata.dev/it/docs/guides/troubleshooting/reference.md#credentials)

<a id="fixes"></a>

## Fissare un controllo fallito

| Risultato | Azione |
| --- | --- |
| accessVerified: false | Leggere la fase e nextCommand. Un profilo in sospeso può restituire ok: true prima che una chiave sia utilizzabile. Terminare la registrazione o la richiesta salvata; conservare lo stesso profilo. |
| access: blocked | Smettere anche se la risposta HTTP era 200. Verificare l'account o la connessione nella console; non trattare una risposta di identità come permesso di query. |
| accountType: temporary | Utilizzare la prova ammissibile per un lavoro di una tantum. Pretendiamolo prima della pianificazione; una nuova connessione OAuth non richiede questo profilo. |
| installed: false | Dopo l'approvazione del proprietario, eseguire flashdata auth finish --wait con il profilo originale e la directory di stato. Allora ripeti l'assegno. |
| 401 / invalid_grant | Ricollegare le credenziali scadute o revocate nel suo host originale. Non avviare un altro prova per bypassarlo. |
| 403 / source_forbidden | Controlla gli ambiti della chiave o l'elenco sorgente OAuth. YouTube Download utilizza un tasto API proprietario. |
| Accesso valido, saldo zero | L'autenticazione funziona. Controllare Billing prima del lavoro pagato; non sostituire una chiave valida. |

- [Billing](https://flashdata.dev/app/billing)
- [Recuperare una connessione interrotta](https://flashdata.dev/it/docs/guides/agent-recovery/reference.md)
