Your identity provider knows every human who can touch BigQuery: their groups, their lifecycle, the day they offboard. It usually knows nothing about your agents. They authenticate with a JSON key that exists outside the IdP, has no owner, no expiry policy, and no group membership. That gap is the real meaning of an unmanaged non-human identity.
Building a real non-human identity for AI agents on BigQuery means pulling agents into the same identity system that governs humans. Each agent becomes a principal you can authenticate, attribute, and revoke, instead of a static secret that lives on forever.
Agents deserve first-class principals
Treating an agent as a copyable key file has consequences that show up later. You cannot answer "which agents can read this dataset" without grepping for key files. You cannot offboard a retired agent by disabling an identity, because there is no identity, only a credential someone has to remember to revoke. And you cannot attribute anything, because everything sharing the key is the same principal.
A first-class non-human identity fixes all three. The agent authenticates as itself, so it has a lifecycle, a scope, and an audit footprint.
A non-human identity needs the same lifecycle as a human one
The useful test is to ask whether your agents go through the same lifecycle events your employees do. A human is provisioned in the IdP, assigned to groups, granted scoped access, and disabled the day they leave, with every action attributable to them along the way. A static key file does none of this. It is born outside the IdP, belongs to no one, and dies only when someone remembers it exists.
A real non-human identity closes that gap. The agent is a principal in the same system, so you can list it, scope it, attribute its queries, and revoke it in one place. The identity has a beginning and an end, which is what makes the rest of your access controls mean anything when applied to it.
Where the identity is brokered for BigQuery
hoop.dev sits between identities and infrastructure, and it proxies the connection to BigQuery. The agent authenticates to the gateway, and with GCP IAM federation enabled, hoop.dev brokers a per-user, short-lived OAuth token for that session rather than handing over a shared service-account key. The non-human identity is established at the gateway and never materializes as a durable secret on the agent.
This is the key architectural move: the credential is minted per session against your IdP and GCP federation, so the agent's identity is real and revocable, and there is no key file to leak.
Steps
- Run the hoop.dev agent near your GCP project, connecting outbound to the gateway.
- Register a BigQuery connection, set
CLOUDSDK_CORE_PROJECT, and enable GCP IAM federation so the connection issues per-user OAuth rather than reading a shared key file. - Map the agent to a principal in your IdP and bind it to the connection so the gateway can authenticate and attribute it.
- Route the agent's
bq calls through the gateway.
# the agent authenticates as itself; no key file on disk
bq query --use_legacy_sql=false \
'SELECT product, SUM(units) FROM sales.orders GROUP BY product'
Verify
Disable the agent's principal in your IdP and confirm it can no longer open a BigQuery session through the gateway. That clean revoke is the proof you have a managed identity rather than a floating key.
Pitfalls
- Do not leave a fallback static key alongside the federated identity; it undoes the lifecycle you just gained.
- Do not give one identity to many agents. Per-agent principals are what make attribution and offboarding work.
- Do not over-scope the federated identity's IAM roles. A real identity with godlike roles is still dangerous.
hoop.dev is open source, so you can confirm how identities are brokered before trusting them. Read the getting started guide and see how this identity model enables just-in-time access for AI agents on BigQuery. Start at github.com/hoophq/hoop and federate a test agent's identity to a BigQuery connection.
FAQ
Can I revoke an agent's BigQuery access in one place?
Yes. When the agent authenticates through hoop.dev as an IdP principal, disabling that principal stops it opening sessions, so there is no orphaned key file to chase down.
Does the agent store a Google credential?
No. With GCP IAM federation, hoop.dev brokers a short-lived OAuth token per session. The agent never holds a durable service-account key.
