App API keys and request history

An app API key lets a program call selected routes while the browser UI stays behind sign-in. Your own agent needs none: it calls the app with your floo API key, as you. See Let your agent call your app. App keys grant no floo administration access. They belong to one app, not to an org or environment, and work in dev and production wherever that app’s deployed route policy accepts their scopes.

Declare the API path

For a multi-service app, add these entries to floo.app.toml. This example assumes your declared services are named web and api, both with public ingress.

[[routes]]
path = "/"
service = "web"
access = "accounts"

[[routes]]
path = "/api"
service = "api"
access = "accounts"

[[routes]]
path = "/integrations/v1"
service = "api"
access = "api_key"
scope = "reports.access"

The API service implements /integrations/v1 and its endpoints; floo forwards the full path unchanged. A FastAPI fixture:

@app.get("/integrations/v1/status")
def integration_status():
    return {"ok": True}

Commit and push the declaration; the deploy applies it, and promote carries it to prod. If your org or app has an approval policy that gates access broadening, adding machine access to an existing protected app requires floo org-admin authority: after pushing, an org admin or their authorized agent runs floo redeploy --app <name> --rebuild with an admin-scoped floo credential to apply it in dev, and release and promote reject the broadening while the policy is on. Any separately configured infrastructure-review policy still applies. Explicit multi-service routes replace the default path table on the app host, service aliases, and verified custom domains. See Multi-service routing.

Create a consumer and a scoped key

Create a named consumer and a key scoped to the declared route:

floo apps consumers create daily-report
floo apps keys create daily-report --consumer daily-report --scope reports.access --rate-limit-rpm 60

These commands use the app in your local config. Pass --app <name> to select another app. --consumer accepts an ID or a case-insensitive name. The CLI uses your floo API key; keep it separate from the app key you give the program. Human mode prints only the one-time raw key on stdout; the shown-once notice, key ID, prefix, and scopes go to stderr. Store the raw value directly in the program’s secret store; it cannot be retrieved again. Do not paste it into a chat or prompt, print it in logs, or put it in a URL or repository. Keep the key ID for request-history queries and revocation. To store a new key in another floo app without showing it in the terminal or an agent transcript, pipe it to floo env set. Replace report-worker with the app that will call the API:

floo apps keys create reader --consumer daily-report --scope reports.access | floo env set REPORTS_KEY --stdin --app report-worker

With --json, raw_key is redacted unless you pass the global --reveal-secrets flag. The output sets contains_secrets: true in either case. --scope is required and repeatable. Use --scope '*' only to grant every scope. Scopes are exact-match labels, not HTTP-method permissions: GET and POST under the same scoped route use the same gate. Your application still owns operation and record-level permissions. List consumers and key metadata without redisclosing the key:

floo apps consumers list
floo apps keys list --consumer daily-report

Call the app

The program sends the app key as Authorization: Bearer to the app’s public URL, for example /integrations/v1/status, with no browser cookie. The fixture returns {"ok": true} with status 200. Missing, malformed, revoked, and wrong-app keys return 401. A valid key without the required scope returns 403; a per-key rate-limit rejection returns 429. floo strips the raw key before forwarding the request and supplies verified consumer identity headers instead:

Header	Value
`X-Floo-Auth-Method`	`api_key`
`X-Floo-Api-Key-Id`	The key’s ID
`X-Floo-Api-Key-Name`	The key’s name, when it has one
`X-Floo-Api-Key-Scopes`	The key’s scopes, comma-separated
`X-Floo-Api-Consumer-Id`	The consumer’s ID
`X-Floo-Api-Consumer-Name`	The consumer’s name, when it has one

floo removes any X-Floo-* header the caller sends, so these values always come from the gateway. Sending an app key to the / browser route does not sign the caller in.

Inspect requests by key

Use your floo API key, not the app key:

GET /v1/apps/{app_id}/requests?api_key_id={key_id}&since=1h&limit=100

Each row includes the timestamp, key ID, routed host, HTTP method, path, status, and latency. To page through results, pass the returned next_cursor as cursor and keep the same filters. total counts this page, not all matching requests. The maximum page size is 500. For a fixed interval, use timezone-aware ISO 8601 since and until values; until is exclusive. URL-encode query values. The host filter distinguishes app hostnames and environments. An expired or invalid cursor returns REQUESTS_QUERY_ERROR; restart the query with the intended time range. Verified keys remain attributable on scope and per-key rate-limit failures. Unknown or invalid credentials are not assigned a key identity. Request bodies, authorization headers, cookies, and query strings are not part of this history. History is buffered asynchronously and retained for about seven days, so a request takes time to appear. Buffer overflow or a process crash can lose events: this is request visibility, not a lossless business-change audit log.

Revoke access

Revoke a key by its ID:

floo apps keys revoke KEY_ID

Revocation is idempotent: revoking an already-revoked key succeeds. It is published to gateway instances; if that signal is missed, the validation cache bounds propagation to 30 seconds. Retry the fixture after that window and confirm it returns 401. Creation and revocation are recorded in floo’s key lifecycle audit. Delete a consumer to revoke all its active keys:

floo apps consumers delete daily-report

Deletion requires typed confirmation. In non-interactive or JSON mode, pass the explicit confirmation flag:

floo apps consumers delete daily-report --yes-i-know-this-destroys-data

Next, use Logs and debugging to investigate application errors behind a failed request.

HTTP reference

Use the management API at https://api.getfloo.com with your floo operator credential, kept separate from the app key you give the program. Substitute your app and record IDs in these routes. Create a named consumer:

POST /v1/apps/{app_id}/consumers
Content-Type: application/json

{"name": "daily-report"}

Use the returned consumer id to create its key:

POST /v1/apps/{app_id}/consumers/{consumer_id}/keys
Content-Type: application/json

{"name": "daily-report", "scopes": ["reports.access"], "rate_limit_rpm": 60}

The response contains a non-secret key id and a one-time raw_key. Always set scopes explicitly in HTTP requests; omitting them grants the wildcard default. Inventory endpoints return metadata without redisclosing the key:

GET /v1/apps/{app_id}/consumers
GET /v1/apps/{app_id}/consumers/{consumer_id}/keys

Revoke a key:

DELETE /v1/apps/{app_id}/api-keys/{key_id}

A successful response is 204, including when the key was already revoked. Delete a consumer and revoke all its active keys:

DELETE /v1/apps/{app_id}/consumers/{consumer_id}

Get started

Build with your stack

Deploy from your agent

Configure your app

Ship and release

Data

Domains and networking

App users and access

Operate

Team and billing

For agents

App API keys and request history

Declare the API path

Create a consumer and a scoped key

Call the app

Inspect requests by key

Revoke access

HTTP reference

​Declare the API path

​Create a consumer and a scoped key

​Call the app

​Inspect requests by key

​Revoke access

​HTTP reference

Declare the API path

Create a consumer and a scoped key

Call the app

Inspect requests by key

Revoke access

HTTP reference