Skip to content
EN
Get API key
Browse documentation

Integrations

Agent authentication options

Connect with an API key or MCP OAuth, verify access without a paid query, and reuse it for later tasks.

On this page

1. Choose and connect

Already connected? Go straight to the free check in step 2. Otherwise, choose the access your application or agent needs.

You are connectingUseWho keeps the credential?
An app, SDK, CLI or scheduled scriptOwner API keyYour server's secret store or CLI profile
Codex or OpenClaw research toolsMCP OAuthThe host after browser consent
An agent trying FlashData without an accountTemporary API keyThe agent's saved trial profile, then owner access after claiming

Create a key in API Keys with the sources your task needs, or reuse an existing key. Supply it to your SDK or send it as X-API-Key from your backend. The Bash and PowerShell checks in step 2 work directly with the API; no CLI installation is required.

Which sources can this credential use?

Use X-API-Key for normal HTTP requests and API-key MCP connections. OAuth bearer tokens work only at the hosted MCP endpoint. YouTube Download needs an owner API key with youtube_download and destination storage.

CredentialAvailable sources
Owner API keyThe sources granted to the key, including youtube_download when approved.
Temporary API keyOnly granted trial-eligible sources. Read scopes from the current identity response.
MCP OAuthgoogle_search, youtube_search, youtube_metadata, youtube_transcript

Save a key in the CLI

Skip import if the CLI already has access or your secret manager supplies FLASHDATA_API_KEY. Otherwise, choose a method below and keep the same research profile for later commands. A saved CLI key is not automatically available to SDKs or local MCP servers.

Paste the key at the hidden terminal prompt.

Import once
flashdata auth login --profile research

2. Verify the connection

Run the free check in the environment that will perform the task. CLI and HTTP checks use an API key; the MCP check uses the host's own saved connection.

Requires Bash and cURL 7.76+. Skip the hidden key prompt if your environment already supplies FLASHDATA_API_KEY. Run the read commands in the same terminal.

Set the key · skip if already configured
# 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
Read account JSON
(
: "${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'
)

Read the API-key identity

HTTP identity fields are at the top level. In CLI JSON, read data.identity.identity and require data.accessVerified: true. HTTP 200 or CLI ok: true alone is not enough.

CheckRequired result
Intended accountaccountId and apiKeyId identify the account and key you meant to use.
Usable accessaccess: ready
Task permissionscopes contains the source, such as google_search. CLI also lists the allowed sources in data.identity.permittedSources.
Recurring taskaccountType: owned · installed: true · recurringAllowed: true

An active trial is a valid connection

A trial can pass a one-off task check while recurringAllowed is false. Read the actual scopes and expiry; claim the existing trial before scheduling work.

Temporary identity · illustrative fields
{
  "accountType": "temporary",
  "access": "ready",
  "installed": false,
  "recurringAllowed": false,
  "scopes": [
    "google_search"
  ]
}

Find the connection in Codex

List configured servers, then use /mcp in a fresh Codex session. Run the MCP check above to verify the credential.

List servers
codex mcp list

Check the connection in OpenClaw

Probe the saved server, then run the MCP check above in your active conversation.

Probe the server
openclaw mcp doctor flashdata --probe

3. Reuse access for later tasks

Keep the credential store private and persistent across process restarts. Recheck access in a fresh process before enabling your scheduler.

CredentialFor the next task
Owner API keyReuse the saved key. It has no OAuth refresh step; replace it if expired or revoked.
MCP OAuthThe host refreshes one-hour OAuth access tokens using rotating refresh tokens. Reconnect when the 90-day grant expires or is revoked. Each installation owns its token store; do not share refresh-token files between hosts.
Temporary API keyFinish owner claiming and credential handoff before recurring work. Reuse the original profile; do not register again for each run.

Check a CLI task before scheduling

Requires Bash and jq. Set SOURCE to the task's source. The script uses research by default; set FLASHDATA_PROFILE and FLASHDATA_STATE_DIR for a different profile or state directory. Exit 0 with identity JSON means the owner key is ready, installed and permitted for this source. Have your scheduler stop on any other exit. No query is submitted.

Fresh-process access check · 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}'
)

If access is still a trial

Complete the trial and claiming guide with the original profile. After owner approval and credential handoff, the free check should show owned access and recurringAllowed: true. Continued requests use the owner's shared balance; unused trial credits do not transfer. MCP OAuth login is a separate connection and does not claim this trial.

Revoke access

Pause recurring jobs first. Revoke the matching credential below, then repeat the free check from a fresh process or session before clearing local access. Expect authentication failure or a reconnect request; do not approve a new connection during the check. Local logout alone does not revoke server access.

ConnectionWhere to revoke
MCP OAuthSettings → Connected apps → the app's grant.
Claimed agent API keySettings → Connected apps → Agent connections.
Account API keyAPI Keys → the key used by this integration.

Fix a failed check

ResultAction
accessVerified: falseRead phase and nextCommand. A pending profile can return ok: true before a key is usable. Finish its saved registration or claim; retain the same profile.
access: blockedStop even if the HTTP response was 200. Review the account or connection in the console; do not treat an identity response as permission to query.
accountType: temporaryUse the eligible trial for one-off work. Claim it before scheduling; a new OAuth connection does not claim this profile.
installed: falseAfter owner approval, run flashdata auth finish --wait with the original profile and state directory. Then repeat the check.
401 / invalid_grantReconnect the expired or revoked credential in its original host. Do not start another trial to bypass it.
403 / source_forbiddenCheck the key's scopes or the OAuth source list. YouTube Download uses an owner API key.
Valid access, zero balanceAuthentication worked. Check Billing before paid work; do not replace a valid key.