# Opciones de autenticación para agentes

Conecta con una clave API o MCP OAuth, verifica el acceso sin una consulta de pago y reutilízalo en tareas posteriores.

Referencia canónica: https://flashdata.dev/es/docs/guides/agent-access
Revisado: 2026-11-05 por FlashData

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

## 1. Elige cómo conectarte

Si ya tienes acceso, pasa a la comprobación gratuita del paso 2. Si no, elige la opción que necesita tu aplicación o agente.

| Qué conectas | Opción | Quién guarda la credencial |
| --- | --- | --- |
| Una aplicación, SDK, CLI o script programado | Clave API del titular | El gestor de secretos de tu servidor o el perfil de la CLI |
| Herramientas de investigación de Codex u OpenClaw | MCP OAuth | El cliente, tras la autorización en el navegador |
| Un agente que prueba FlashData sin una cuenta | Clave API temporal | El perfil de prueba del agente; tras vincularlo a una cuenta, guarda el acceso del titular |

### Clave API

Crea una clave en API Keys con las fuentes que necesita tu tarea, o reutiliza una existente. Pásala al SDK o envíala en X-API-Key desde tu backend. Las comprobaciones de Bash y PowerShell del paso 2 usan la API directamente y no requieren instalar la CLI.

- [API Keys](https://flashdata.dev/app/api-keys)
- [Guarda una clave en la CLI](https://flashdata.dev/es/docs/guides/agent-access/reference.md#import-key)
- [Configurar la clave para SDK y HTTP](https://flashdata.dev/es/docs/guides/api-keys-and-permissions/reference.md#store)

### MCP OAuth

Usa un cliente configurado para OAuth de FlashData. El titular crea una cuenta o inicia sesión y autoriza el acceso en el navegador; el cliente guarda los tokens. Esta conexión no instala una clave en la CLI ni vincula una prueba a una cuenta.

#### Conexión MCP remota

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

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

### Prueba para agentes

Si el agente no tiene clave, consulta los requisitos actuales de la prueba antes de registrarlo. Reutiliza una prueba existente y su perfil. YouTube Download y las tareas recurrentes requieren acceso del titular.

#### Consultar antes de registrarse

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

- [Iniciar una prueba y vincularla a una cuenta](https://flashdata.dev/es/docs/guides/agent-onboarding/reference.md)
- [Protocolo de autenticación del agente](https://flashdata.dev/auth.md)


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

### ¿Qué fuentes permite la credencial?

Usa X-API-Key en las solicitudes HTTP y en las conexiones MCP con clave API. Los tokens OAuth solo funcionan en el endpoint MCP remoto. YouTube Download requiere una clave API del titular con permiso youtube_download y un destino de almacenamiento.

| Credencial | Fuentes disponibles |
| --- | --- |
| Clave API del titular | Las fuentes autorizadas en la clave, incluido youtube_download si se ha aprobado. |
| Clave API temporal | Solo las fuentes autorizadas y disponibles en la prueba. Consulta scopes en la respuesta de identidad actual. |
| MCP OAuth | google_search, youtube_search, youtube_metadata, youtube_transcript |


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

### Guarda una clave en la CLI

Omite la importación si la CLI ya tiene acceso o tu gestor de secretos proporciona FLASHDATA_API_KEY. Si no, elige un método y conserva el perfil research para los siguientes comandos. Una clave guardada en la CLI no se proporciona automáticamente a los SDK ni a los servidores MCP locales.

#### Terminal interactiva

Pega la clave cuando la terminal la solicite; la entrada no se muestra en pantalla.

##### Importar una vez

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


#### Automatización · Bash

Define FLASHDATA_KEY_FILE con la ruta de un archivo protegido que ya contenga la clave. El comando la lee por la entrada estándar (stdin). No pegues la clave en el chat ni en los argumentos del comando.

##### Importar desde un archivo protegido

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


- [Instalar la CLI](https://flashdata.dev/es/docs/guides/flashdata-cli/reference.md#install)

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

## 2. Verifica la conexión

Ejecuta la comprobación gratuita en el entorno donde se realizará la tarea. La CLI y HTTP usan una clave API; MCP usa la conexión guardada del cliente.

### Bash / cURL

Requiere Bash y cURL 7.76+. Si FLASHDATA_API_KEY ya está definida en tu entorno, omite el paso para introducirla. Ejecuta los comandos en la misma terminal.

#### Define la clave si aún no está configurada

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

#### Leer el JSON de la cuenta

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

Si FLASHDATA_API_KEY ya está definida, omite el paso para introducirla. Ejecuta los comandos en la misma terminal.

#### Define la clave si aún no está configurada

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

#### Leer el JSON de la cuenta

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

Usa el mismo usuario del sistema, perfil y directorio de estado que al iniciar sesión. Sustituye research por tu perfil y añade --state-dir PATH si corresponde. FLASHDATA_API_KEY tiene prioridad sobre la clave guardada. Comprueba ok: true y data.accessVerified: true, y revisa los campos de identidad siguientes.

#### Consultar la cuenta gratis

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

- [Configurar una clave](https://flashdata.dev/es/docs/guides/api-keys-and-permissions/reference.md#store)

### MCP

Envía este mensaje en una nueva sesión del agente conectado. Sustituye google_search por la fuente de tu tarea. Ambas llamadas deben completarse sin errores; revisa el precio y el saldo antes de ejecutar trabajo de pago. Que el servidor aparezca en la lista no confirma el acceso.

#### Comprobar la conexión

```text
Usa la conexión MCP flashdata existente.
Llama a get_pricing con {"source":"google_search","request_count":1}.
Llama a get_balance con {}.
Indica si ambas llamadas se completaron sin errores, si hay un precio disponible para la fuente
y cuántos créditos quedan. Un saldo de cero no es un fallo de autenticación.
No ejecutes búsquedas ni descargas. No crees una prueba ni cambies las credenciales.
```



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

### Comprueba la identidad de la clave API

En la respuesta HTTP, los campos de identidad están en el nivel superior. En el JSON de la CLI, lee data.identity.identity y exige data.accessVerified: true. Un HTTP 200 o un ok: true de la CLI no bastan.

| Verifica | Resultado requerido |
| --- | --- |
| Cuenta correcta | accountId y apiKeyId corresponden a la cuenta y la clave que quieres usar. |
| Acceso listo | access: ready |
| Permiso de la tarea | scopes incluye la fuente, por ejemplo google_search. La CLI también muestra las fuentes permitidas en data.identity.permittedSources. |
| Tarea periódica | accountType: owned · installed: true · recurringAllowed: true |

- [Automatizar la comprobación antes de programar](https://flashdata.dev/es/docs/guides/agent-access/reference.md#recurring-check)

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

### Una prueba activa también es una conexión válida

Una prueba puede servir para una tarea puntual aunque recurringAllowed sea false. Revisa los permisos y la fecha de caducidad reales. Vincula la prueba existente a una cuenta antes de programar tareas.

#### Identidad temporal · ejemplo de campos

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


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

### Localiza la conexión en Codex

Lista los servidores configurados y abre /mcp en una nueva sesión de Codex. Ejecuta la comprobación MCP anterior para verificar la credencial.

#### Listar servidores

```bash
codex mcp list
```

- [Configurar Codex y ejecutar la primera tarea](https://flashdata.dev/es/docs/integrations/codex/reference.md)

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

### Comprueba la conexión en OpenClaw

Comprueba el servidor guardado y ejecuta el mensaje de comprobación MCP anterior en tu conversación activa.

#### Comprobar el servidor

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

- [Configurar OpenClaw y ejecutar la primera tarea](https://flashdata.dev/es/docs/integrations/openclaw/reference.md)

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

## 3. Reutiliza el acceso en otras tareas

Guarda las credenciales en un almacén privado que persista al reiniciar el proceso. Comprueba el acceso en un proceso nuevo antes de activar el programador de tareas.

| Credencial | Para la próxima tarea |
| --- | --- |
| Clave API del titular | Reutiliza la clave guardada. No requiere renovación OAuth; sustitúyela si caduca o se revoca. |
| MCP OAuth | El cliente renueva los tokens de acceso OAuth, válidos durante una hora, mediante tokens de renovación rotatorios. Vuelve a conectar cuando la autorización de 90 días caduque o se revoque. Cada instalación guarda sus propios tokens; no compartas archivos de tokens de renovación entre clientes. |
| Clave API temporal | Completa la vinculación a una cuenta y la entrega de la credencial del titular antes de programar tareas. Conserva el perfil original; no te registres de nuevo en cada ejecución. |

- [Cómo ejecutar tareas recurrentes](https://flashdata.dev/es/docs/guides/recurring-tasks/reference.md)

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

### Comprueba la CLI antes de programar

Requiere Bash y jq. Define SOURCE con la fuente de tu tarea. El perfil predeterminado es research; usa FLASHDATA_PROFILE y FLASHDATA_STATE_DIR para cambiar el perfil o directorio. Un código 0 con JSON de identidad confirma que la clave del titular está lista, instalada y autorizada para esa fuente. El programador debe detenerse ante cualquier otro código de salida. No se envían consultas.

#### Comprobar el acceso en un proceso nuevo · 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}'
)
```

- [Añadir precio, saldo y ejecución periódica](https://flashdata.dev/es/docs/guides/recurring-tasks/reference.md#prepare)

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

### Si aún usas una prueba

Sigue la guía de prueba y vinculación con el perfil original. Tras la aprobación del titular y la entrega de la credencial, la comprobación gratuita debe mostrar acceso owned y recurringAllowed: true. Las siguientes solicitudes usan el saldo compartido del titular; los créditos de prueba sin usar no se transfieren. Iniciar sesión con MCP OAuth crea una conexión independiente y no vincula esta prueba.

- [Comandos de prueba y vinculación](https://flashdata.dev/es/docs/guides/agent-onboarding/reference.md)
- [auth.md](https://flashdata.dev/auth.md)

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

## Revoca el acceso

Pausa primero las tareas recurrentes. Revoca la credencial correspondiente y repite la comprobación gratuita en un proceso o sesión nuevos antes de borrar el acceso local. La autenticación debe fallar o pedir que vuelvas a conectar; no autorices otra conexión durante la comprobación. Cerrar la sesión local no revoca el acceso en el servidor.

| Conexión | Dónde revocarlo |
| --- | --- |
| MCP OAuth | Settings → Connected apps → la autorización de la aplicación. |
| Clave de un agente vinculado | Settings → Connected apps → Agent connections. |
| Clave API de la cuenta | API Keys → la clave utilizada por esta integración. |

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

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

## Resuelve una comprobación fallida

| Resultado | Qué hacer |
| --- | --- |
| accessVerified: false | Consulta phase y nextCommand. Un perfil pendiente puede devolver ok: true antes de que la clave sea utilizable. Completa el registro o la vinculación pendientes con el mismo perfil. |
| access: blocked | Detén la tarea aunque la respuesta HTTP sea 200. Revisa la cuenta o la conexión en la consola; recibir la identidad no significa que tengas permiso para consultar datos. |
| accountType: temporary | Usa la prueba para tareas puntuales permitidas. Vincúlala a una cuenta antes de programar tareas; una conexión OAuth nueva no vincula este perfil. |
| installed: false | Tras la aprobación del titular, ejecuta flashdata auth finish --wait con el perfil y el directorio de estado originales. Después, repite la comprobación. |
| 401 / invalid_grant | Vuelve a conectar la credencial caducada o revocada desde su cliente original. No crees otra prueba para eludir el bloqueo. |
| 403 / source_forbidden | Revisa scopes en la clave o la lista de fuentes de OAuth. YouTube Download usa una clave API del titular. |
| Acceso válido, saldo cero | La autenticación funciona. Revisa Billing antes de ejecutar trabajo de pago; conserva la clave válida. |

- [Billing](https://flashdata.dev/app/billing)
- [Recuperar una conexión interrumpida](https://flashdata.dev/es/docs/guides/agent-recovery/reference.md)
