An AI agent that queries BigQuery needs credentials, and the fastest way to give it some is the worst one: drop a Google service-account JSON key on disk and point the agent at it. That key is a non-human identity in the loosest sense. It authenticates, but it answers no useful question. Who ran the query? Which agent? Under whose authority? The key cannot say, because it is one static secret shared by everything that holds it.
Configuring a real non-human identity for an agent on BigQuery means the opposite of a shared key. It means each agent run authenticates as itself, against an identity provider, with a credential that is short-lived and attributable. This is the difference between an agent that the platform team can govern and one that is a standing liability the day it is provisioned. The rest of this guide walks through what goes wrong with the easy approach, what a brokered identity looks like for BigQuery specifically, and how to stand one up.
Why a shared service-account key is not a non-human identity worth having
A service-account key file has three properties that work against you. It is long-lived, so it sits valid for months. It is shared, so every process that can read the file becomes indistinguishable at the BigQuery audit layer. And it is copyable, so a key that leaks into a log line or a container image keeps working until someone notices and rotates it.
For a human, you would never accept this. You would route them through your identity provider and issue a session. An autonomous agent deserves the same treatment, because it acts faster, runs more often, and never gets tired enough to stop.
What a brokered non-human identity looks like for BigQuery
BigQuery supports GCP IAM federation. When an agent connects through hoop.dev with federation enabled, the gateway brokers a per-user, short-lived OAuth token instead of handing over a static key. The agent runs the native bq client through the gateway agent, and the credential it carries is minted for that session and expires when the session ends.
The architectural point is that the identity decision moves off the agent's host. The agent does not hold a key it can leak. It connects to hoop.dev, the gateway resolves who is calling, and federation produces a scoped OAuth credential for that call. The non-human identity is brokered at the boundary, not baked into the workload.
Setup steps
- Deploy the hoop.dev agent inside the network that can reach your GCP project, so it opens an outbound connection to the gateway and nothing is exposed inbound.
- Register a BigQuery connection. Set
CLOUDSDK_CORE_PROJECT to the target project and enable GCP IAM federation so the connection mints per-user OAuth rather than reading a shared GOOGLE_APPLICATION_CREDENTIALS file. - Bind the connection to the agent's identity in your IdP, so the agent authenticates as a first-class principal and the gateway can attribute every query to it.
- Point the agent's
bq calls at the hoop.dev endpoint. From the agent's side nothing changes except where it connects.
# the agent's query runs through the gateway, not against a key file
bq query --use_legacy_sql=false \
'SELECT order_id, region FROM analytics.orders LIMIT 100'
Verify it
Run a query as the agent, then open the session in hoop.dev. You should see the agent's identity, the exact statement it ran, and a session bound to a credential that no longer exists. Rotate nothing, because there is no standing key to rotate.
Pitfalls to avoid
- Do not fall back to the shared key for one service "just to ship." A single static credential reintroduces the problem you removed.
- Do not grant the federated identity broad
roles/bigquery.dataEditor on the whole project. Scope it to the datasets the agent legitimately needs. - Do not log the OAuth token. The point of short-lived federation is that there is nothing durable to log in the first place.
hoop.dev is open source, and you can read exactly how the gateway brokers identity to a target before you trust it with one. To go deeper, see the getting started guide and how the same model gives AI agents on BigQuery just-in-time access rather than standing grants. Start with the source at github.com/hoophq/hoop and wire a federated connection in a test project.
FAQ
Is a service account a non-human identity?
A service account is a non-human principal, but a static key file shared across workloads gives you no attribution. A non-human identity worth governing is per-agent and short-lived, which is what GCP IAM federation through hoop.dev provides.
Does the agent ever hold the BigQuery credential?
No. The agent connects to hoop.dev, and the gateway brokers the credential for that session. The token is scoped to the call and expires with it, so the workload never stores a durable secret.
