# Opções de autenticação do agente

Conecte-se com uma chave API ou MCP OAuth, verifique o acesso sem uma consulta paga, e reutilize-o para tarefas posteriores.

Referência canônica: https://flashdata.dev/pt/docs/guides/agent-access
2026-11-05 por FlashData

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

## 1. Escolha e conecte-se

Já conectado? Vá direto para o verificação grátis no passo 2. Caso contrário, escolha o acesso que sua aplicação ou agente precisa.

| Você está se conectando | Use | Quem fica com a credencial? |
| --- | --- | --- |
| Um aplicativo, SDK, CLI ou script agendado | Chave API | A loja secreta do seu servidor ou o perfil CLI |
| Codex ou OpenClaw ferramentas de pesquisa | MCP OAuth | O anfitrião após o consentimento do navegador |
| Um agente tentando FlashData sem uma conta | Chave temporária API | O agente salvou o perfil do teste, e depois o acesso do proprietário depois de alegar |

### API chave

Crie uma chave no API Keys com as fontes que sua tarefa precisa, ou reutilize uma chave existente. Forneça-o para o seu SDK ou envie-o como X-API-Key de sua infraestrutura. Bash e PowerShell verificam na etapa 2 trabalham diretamente com API; nenhuma instalação CLI é necessária.

- [API Keys](https://flashdata.dev/app/api-keys)
- [Guarde uma chave no CLI](https://flashdata.dev/pt/docs/guides/agent-access/reference.md#import-key)
- [SDK e configuração de chave HTTP](https://flashdata.dev/pt/docs/guides/api-keys-and-permissions/reference.md#store)

### MCP OAuth

Use um host configurado para FlashData OAuth. O dono da conta completa a inscrição ou a inscrição e o consentimento no navegador; o anfitrião salva os símbolos. Esta conexão não instala uma chave CLI ou reivindica um teste.

#### Ligação MCP hospedada

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

- [Conectar Codex](https://flashdata.dev/pt/docs/integrations/codex/reference.md#setup)
- [Conectar OpenClaw](https://flashdata.dev/pt/docs/integrations/openclaw/reference.md#setup)
- [Outros clientes MCP](https://flashdata.dev/pt/docs/integrations/mcp-clients/reference.md#connect)

### Agente teste

Para um agente sem chave, discover a elegibilidade atual para o teste antes de se registrar. Reutilize um teste existente e seu perfil. YouTube Download e tarefas recorrentes requerem acesso do proprietário.

#### Descubra sem registro

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

- [Comece um teste e reivindique](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md)
- [Protocolo de autenticação do agente](https://flashdata.dev/auth.md)


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

### Que fontes essa credencial pode usar?

Use X-API-Key para pedidos normais de HTTP e conexões API-chave MCP. OAuth tokens ao portador funcionam apenas no ponto final hospedado do MCP. YouTube Download precisa de uma chave API com youtube_download e armazenamento de destino.

| Credencial | Fontes disponíveis |
| --- | --- |
| Chave API | As fontes concedidas à chave, incluindo youtube_download quando aprovado. |
| Chave temporária API | Apenas fontes elegíveis para o teste. Leia os escopos da atual resposta de identidade. |
| MCP OAuth | google_search, youtube_search, youtube_metadata, youtube_transcript |


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

### Guarde uma chave no CLI

Pular importação se o CLI já tem acesso ou seu gerente secreto fornece FLASHDATA_API_KEY. Caso contrário, escolha um método abaixo e mantenha o mesmo perfil de pesquisa para comandos posteriores. Uma chave CLI salva não está disponível automaticamente para servidores SDKs ou MCP locais.

#### Terminal interativo

Cola a chave no terminal secreto.

##### Importar uma vez

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


#### Automação · Bash

Defina FLASHDATA_KEY_FILE para o caminho de um arquivo de chave protegida existente. O comando lê através do stdin; mantenha a chave fora dos argumentos de bate-papo e comando.

##### Leia um segredo protegido através de 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"
```


- [Instalação CLI](https://flashdata.dev/pt/docs/guides/flashdata-cli/reference.md#install)

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

## 2. Verifique a conexão

Faça a verificação gratuita no ambiente que irá realizar a tarefa. As verificações CLI e HTTP usam uma chave API; a verificação MCP usa a conexão salva do próprio hospedeiro.

### Bash / cURL

Requer Bash e cURL 7.76+. Pule a chave secreta se seu ambiente já fornecer FLASHDATA_API_KEY. Execute os comandos de leitura no mesmo terminal.

#### Defina a tecla · skip se já configurado

```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
```

#### Leia a conta 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

Pule o prompt de chave escondida se FLASHDATA_API_KEY já está definido. Execute os comandos de leitura no mesmo terminal.

#### Defina a tecla · skip se já configurado

```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
```

#### Leia a conta 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

Use o usuário OS, perfil e diretório de estado do login. Substitua a pesquisa se usar outro perfil, adicione --state-dir PATH se necessário. FLASHDATA_API_KEY substitui a chave salva. Espere ok: true e data.accessVerified: true; então inspecione os campos de identidade abaixo.

#### Conta livre lê

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

- [Prepare uma chave](https://flashdata.dev/pt/docs/guides/api-keys-and-permissions/reference.md#store)

### MCP

Envie isso para uma nova sessão do seu agente conectado. Substitua google_search pela fonte que sua tarefa precisa. Espere que ambas as chamadas sejam bem sucedidas, verifique os preços e o equilíbrio separadamente antes do trabalho pago. Um servidor listado sozinho não verifica o acesso.

#### Conexão checada

```text
Use os dados de conexão MCP existentes.
Chame get_pricing com {"source":"google_search","request_count":1}.
Chame get_balance com {}.
Relate se ambas as chamadas tiveram sucesso, se a fonte tem um preço disponível,
e o saldo de crédito disponível. Um equilíbrio zero não é uma falha de autenticação.
Não faça uma busca ou download, crie um teste ou mude de credenciais.
```



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

### Leia a identidade da chave API

Os campos de identidade HTTP estão no nível superior. Em CLI JSON, leia data.identity.identity e requeira data.accessVerified: true. HTTP 200 ou CLI ok: true sozinho não é suficiente.

| verificação | Resultado necessário |
| --- | --- |
| Conta prevista | accountId e apiKeyId identificam a conta e a chave que você queria usar. |
| Acesso utilizável | access: ready |
| Permissão da tarefa | escopos contém a fonte, como google_search. CLI também lista as fontes permitidas em data.identity.permittedSources. |
| Tarefa recorrente | accountType: owned · installed: true · recurringAllowed: true |

- [Automatize esses verificações antes de agendar](https://flashdata.dev/pt/docs/guides/agent-access/reference.md#recurring-check)

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

### Um teste ativo é uma conexão válida

Um teste pode passar por uma tarefa única, enquanto recurringAllowed é false. Leia os escopos e expire, reclame o teste existente antes de agendar o trabalho.

#### Identidade temporária · campos ilustrativos

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


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

### Encontre a conexão em Codex

Liste os servidores configurados, e use /mcp em uma nova sessão Codex. Faça a verificação MCP acima para verificar a credencial.

#### Listar servidores

```bash
codex mcp list
```

- [Codex configuração e primeira tarefa](https://flashdata.dev/pt/docs/integrations/codex/reference.md)

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

### Verifique a conexão em OpenClaw

Sonda o servidor salvo, então execute a verificação MCP acima em sua conversa ativa.

#### Sonda o servidor

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

- [OpenClaw configuração e primeira tarefa](https://flashdata.dev/pt/docs/integrations/openclaw/reference.md)

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

## 3. Reutilize o acesso em tarefas futuras

Mantenha a loja de credenciais privada e persistente em todo o processo reiniciado. Verifique novamente o acesso em um novo processo antes de habilitar seu agendador.

| Credencial | Para a próxima tarefa |
| --- | --- |
| Chave API | Reutilize a chave salva. Não tem nenhum passo de atualização OAuth; substitua se expirar ou revogar. |
| MCP OAuth | O host atualiza fichas de acesso OAuth de uma hora usando fichas rotativas de atualização. Reconecte-se quando o subsídio de 90 expirar ou for revogado. Cada instalação possui sua loja de fichas, não compartilhe arquivos de atualização entre os anfitriões. |
| Chave temporária API | Termino a vinculação do dono e a transferência de credenciais antes do trabalho recorrente. Reutilize o perfil original, não se registre novamente para cada corrida. |

- [Fluxo de trabalho de tarefa recorrente](https://flashdata.dev/pt/docs/guides/recurring-tasks/reference.md)

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

### Verifique uma tarefa CLI antes de agendar

Requer Bash e jq. Defina a fonte da tarefa. O script usa pesquisa por padrão, definir FLASHDATA_PROFILE e FLASHDATA_STATE_DIR para um perfil ou diretório de estado diferente. Sair de 0 com identidade JSON significa que a chave do proprietário está pronta, instalada e permitida para esta fonte. Faça seu agendador parar em qualquer outra saída. Nenhuma consulta foi submetida.

#### Checagem de acesso de 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}'
)
```

- [Adicione preços, equilíbrio e um corredor recorrente](https://flashdata.dev/pt/docs/guides/recurring-tasks/reference.md#prepare)

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

### Se o acesso ainda for um teste

Complete o teste e reivindique o guia com o perfil original. Após aprovação do proprietário e transferência de credenciais, o verificação livre deve mostrar acesso próprio e recurringAllowed: true. Pedidos contínuos usam o equilíbrio compartilhado do proprietário, créditos não usados não são transferidos. MCP OAuth login é uma conexão separada e não reivindica este teste.

- [teste e ordens de vinculação](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md)
- [auth.md](https://flashdata.dev/auth.md)

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

## Revogar o acesso

Pausar trabalhos recorrentes primeiro. Revogar a credencial correspondente abaixo, então repetir a verificação livre de um novo processo ou sessão antes de limpar o acesso local. Espere falha na autenticação ou um pedido de reconexão; não aprove uma nova conexão durante a verificação. O login local sozinho não revoga o acesso ao servidor.

| Ligação | Onde revogar? |
| --- | --- |
| MCP OAuth | Settings → Connected apps → A bolsa do aplicativo. |
| Alegado agente API chave | Settings → Connected apps → Conexões de agentes. |
| Conta API chave | API Keys → a chave usada por esta integração. |

- [Connected apps](https://flashdata.dev/app/settings/connections)
- [API Keys](https://flashdata.dev/app/api-keys)
- [Resolver problemas de acesso](https://flashdata.dev/pt/docs/guides/troubleshooting/reference.md#credentials)

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

## Conserte uma verificação falhada

| Resultado | Ação |
| --- | --- |
| accessVerified: false | Fase de leitura e nextCommand. Um perfil pendente pode devolver ok: true antes que uma chave seja utilizável. Termine seu registro ou vinculação, mantenha o mesmo perfil. |
| access: blocked | Pare mesmo que a resposta HTTP fosse 200. Revise a conta ou conexão no console, não trate uma resposta de identidade como permissão para perguntar. |
| accountType: temporary | Use o teste elegível para um trabalho único. Reclame antes de agendar, uma nova conexão OAuth não reivindica este perfil. |
| installed: false | Após a aprovação do proprietário, execute flashdata auth finish --wait com o perfil original e diretório de estado. Então repita o verificação. |
| 401 / invalid_grant | Reconectar a credencial expirada ou revogada em seu hospedeiro original. Não comece outro teste para evitar. |
| 403 / source_forbidden | Verifique os escopos da chave ou a lista de fontes OAuth. YouTube Download usa uma chave API do proprietário. |
| Acesso válido, equilíbrio zero | A autenticação funcionou. Verifique Billing antes do trabalho pago, não substitua uma chave válida. |

- [Billing](https://flashdata.dev/app/billing)
- [Recupere uma conexão interrompida](https://flashdata.dev/pt/docs/guides/agent-recovery/reference.md)
