Agent identity requires the
agent-identity feature flag. On Lightdash Cloud, ask Lightdash support to enable it for your organization. On a self-hosted instance, enable the flag.- The person. The default: agents use the same credentials as the person asking, either the project’s shared credentials or that person’s personal warehouse credentials when the project uses them.
- The person’s agent sign-in. Each person connects their agent separately. The warehouse recognizes it as an agent session, so policies can restrict the agent while preserving the person’s own access. For example, an agent can see redacted personally identifiable information (PII) while the person can query the unredacted values.
- A shared agent account. All agents on a project use the access granted to one dedicated warehouse account. Use it when every agent user may see the same data.
Choose who agents run as
In Organization settings → Agents → Identity, select your warehouse’s chip and choose an identity. Only organization admins can change this rule, which applies to every connection of that warehouse type across the organization.
Configure the shared agent accounts or agent integration before changing the rule. Lightdash refuses agent queries when the required identity is unavailable; it never falls back to the person’s or project’s credentials. For agent sign-in, the rule takes effect when you select Turn on after setup.
Manage shared agent accounts
Project admins add credentials under Project settings → Agent identity → Add shared agent account. Set up an account on every connection that agents use, then enable A shared agent account in the organization rule. People using agents have nothing to connect. Every person’s agent gets the shared account’s warehouse access. Grant it only data that every agent user may see. Its grants do not inherit each person’s warehouse restrictions. Keep the tables and fields available to agents within that access; agent tags can restrict which explores and fields they use. Use Test to check the saved account and inspect Signs in as. A successful test proves the connection works, not that the account has the right data access. Verify both an allowed query and a query the account should be denied. Use Replace to rotate credentials or change the account, and Remove to delete it. If the rule still requires a shared account, removing it blocks agent queries on that connection.Preview projects
Preview projects use their parent’s shared agent account for the matching connection. Manage credentials on the parent; the preview’s Agent identity page is read-only, with a link to the parent and a Test action. The original connection matches the parent’s original connection. Extra connections match by name and warehouse type within the same organization. Without a match, the preview has no shared agent account. A preview of a preview uses its direct parent’s account. Grant the parent’s account access to the datasets or schemas used by previews. Anyone who can query a preview can ask agents to query it with that account.My agent identity
Settings → My agent identity shows your agent connections when your organization requires a separate identity. For The person’s agent sign-in, connect your agent here and check its expiry date. For A shared agent account, the page identifies the account type your admin manages; you have nothing to set up. If you disconnect your agent sign-in, or the warehouse revokes it, reconnect here before using agents again.Who can read a saved result
Lightdash checks access whenever someone reads a saved or cached result. The reader must still have access to the project, content, and fields, and their identity must match the identity that produced the result. A person’s own queries cannot reuse results produced by an agent identity, and an agent can read only results produced by its own agent. After an identity, user attribute, or field access change, run the query again if Lightdash reports incompatible access. Results saved before agent identity was enabled also require a fresh query. These checks do not cover scheduled delivery attachments or signed download links.The Lightdash CLI
The CLI runs as the person, using their own warehouse access. Its queries are not marked as agent queries or limited by agent permissions. Thelightdash agent status and lightdash agent connect commands report this limitation; they do not issue an agent credential. On a project that uses a shared agent account, they report that no agent connection is needed.
Troubleshooting
Observe agent activity
Use warehouse query history to audit data access and query costs. Use Lightdash version history and application logs to trace content changes and denied actions. Each record identifies the person or Lightdash service account the agent acted for, along with the agent’s surface and client.Warehouse query tags
Tags identify agent activity for auditing; they do not establish a warehouse identity or enforce access policies. Lightdash keeps agent attribution in its query history and sends it to the warehouse through its query-tagging mechanism.
Client IDs are lowercase. IDs containing unsupported label characters or longer than 60 characters become
h- followed by a stable 32-character hash.
Find agent queries in the warehouse
BigQuery records these tags as job labels; Snowflake records them in the JSONquery_tag. Agent attribution takes priority over other tags when warehouse limits apply. For cost reporting, see Attribute BigQuery cost with job labels.
These examples find MCP queries from the last day. Change agent_surface to audit another surface, or filter by agent_client for a particular client. On BigQuery, replace region-us with your dataset region and use an account that can list the project’s jobs.
user_email on BigQuery and user_name on Snowflake. For other query metadata, see Query tags.
Content version history
Versions of charts, dashboards, SQL charts, documents, and data apps record agent attribution. Chart and dashboard history show Changed by an agent for, followed by the person and surface. Attribution comes from the signed-in credential and agent runtime, so tool arguments and request headers cannot override it.
Application audit logs
The agent action log records writes that do not create a version, such as space changes, scheduled deliveries, share links, and dbt write-back commits. It also records denied actions. Entries include the organization, project, time, agent, object, action, outcome, deciding policy, and reason code. They exclude data, tool arguments, SQL, recipients, URLs, and secrets. Each entry also goes to the application audit log. Self-hosted administrators can use Agent identity audit entries and logs to find them. Retention follows query history, controlled byQUERY_HISTORY_RETENTION_DAYS.
Set up your warehouse
Choose your warehouse for credentials, grants, and policy examples.Snowflake
Snowflake supports verified agent sessions for each person and a dedicated shared user. Both can use warehouse policies to restrict agent access.- One Snowflake account. The organization has one agent integration; every project using per-person agent sign-in must use that Snowflake account.
- Allowed default role. Each person needs a default role outside
ACCOUNTADMIN,SECURITYADMIN,ORGADMIN, andGLOBALORGADMIN, which Snowflake blocks in OAuth sessions.
The person
Agents use the project’s normal Snowflake credentials or the person’s personal warehouse credentials when the project uses them.The person’s agent sign-in
Snowflake OAuth creates a verified agent session for each person. Policies can distinguish that session usingSYS_CONTEXT('SNOWFLAKE$CURRENT', 'IS_AGENT_ACTIVATED'). Without policies, the agent retains the access of the person’s role.
Set up the Snowflake agent integration
An organization admin configures the integration once:- In Organization settings → Agents → Identity, select the Snowflake chip and The person’s agent sign-in.
- Run the provided
CREATE SECURITY INTEGRATIONSQL in Snowflake asACCOUNTADMIN. It includes your instance’s redirect URL and a statement that returns the client ID and secret. - Enter the Snowflake account URL, Client ID, and Client secret, then Save. For example, the account URL is
https://myorg-myaccount.snowflakecomputing.com. - Select Verify integration, then Turn on when the required checks pass. Tell people to connect their agents before they next use AI features.

Connect your agent
In Settings → My agent identity, select Connect agent on the Snowflake card and approve the Snowflake sign-in. Lightdash saves the connection only after verifying that Snowflake marks it as an agent session.
Verify the agent session
Ask an agent to run the check through SQL mode or MCP’srun_sql, then run it in a Snowflake worksheet as the same person:
agent_activated should be true only in the agent session. In SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY, agent_type = 'EXTERNAL_AGENT' confirms a verified agent session; a query tag alone does not. Account usage has an ingestion delay. See QUERY_HISTORY.
Query a protected table both ways to confirm the row, masking, and session policies produce the access you intended.
Shared agent account
Use a dedicated Snowflake user with key-pair authentication. Set its user, private key, role, and warehouse in Lightdash.Create the user and grants
Create an RSA key pair, a role, and a warehouse for agents, then create the user and grant access:TYPE = SERVICE_AGENT marks every session as an agent session, allowing agent-session policies to apply. With another user type, only the role’s grants restrict agents. See SERVICE_AGENT users.
Add and verify the account
In Project settings → Agent identity → Add shared agent account, enter User, Private key, Role, and Warehouse, plus Passphrase if needed. Paste the complete PEM key, including matchingBEGIN and END lines for PRIVATE KEY, RSA PRIVATE KEY, or ENCRYPTED PRIVATE KEY. Testing stays disabled until the required fields and key format are valid. Select Test and save to check the key pair, role, and warehouse.

agent_activated is true for SERVICE_AGENT users.
Snowflake details
- Connection settings. The shared user supplies the user, key, role, and warehouse. The account, database, and schema come from the project connection; its custom query tag does not carry over.
- Integration changes. Replacing the OAuth client invalidates existing agent sign-ins, so each person must reconnect. Switching to The person does not revoke tokens Snowflake already issued.
- Connection lifetime. Lightdash refreshes agent sign-ins until the grant expires, as set by
OAUTH_REFRESH_TOKEN_VALIDITY. My agent identity shows the expiry date. - Role on reconnect. Reconnecting uses the person’s Snowflake default role. Change that role first if the agent has the wrong access.
- Query cache. Agent queries skip the Snowflake result cache.
Write Snowflake policies for agent sessions
Adapt these examples to your data and existing policies before attaching them, using a role with the required policy privileges. The agent-session signal is true only in a verified agent session.Hide rows from agents
A row access policy can exclude sensitive rows from agent sessions:Mask values from agents
A masking policy can hide a value from agent sessions:Use a view on Snowflake Standard Edition
Row access and masking policies need Snowflake Enterprise Edition. On Standard Edition, a view gives the same result for the columns it covers:Limit what an agent session can do
A session policy can limit the privileges of an agent session:Troubleshoot Snowflake agent sign-in
BigQuery
BigQuery enforces access through IAM grants, row access policies, and column masks. For shared agent queries, target the service account rather than each person’s Google identity.The person
Agents use the project’s normal BigQuery credentials or the person’s personal warehouse credentials when the project uses them.Shared agent account
Use a dedicated Google Cloud service account with a JSON key.Create and add the account
- Create a service account for agents, separate from the project’s normal connection account.
- Grant
roles/bigquery.jobUseron the project that runs the jobs, and read access to only the datasets or tables agents need. Avoid project-wide data roles unless agents should read every dataset. - Create a JSON key and upload it under Project settings → Agent identity → Add shared agent account → Service account key file.
- Select Test, check that Signs in as identifies the dedicated service account, then Save.
gcloud and bq commands based on your connection.
Decide what agents can read
The examples uselightdash-agents@my-project.iam.gserviceaccount.com for agents and lightdash@my-project.iam.gserviceaccount.com for the normal connection. Replace them with your accounts.
Datasets
Grantroles/bigquery.dataViewer only on the datasets that agents may use:
Tables
To give agents only some tables in a dataset, grant Data Viewer on each table instead of on the dataset:Columns
Policy tags protect individual columns. You create a taxonomy with a policy tag, for examplepii, and attach it to the sensitive columns. Then you choose what the shared agent account sees in those columns:
- Masked values. Add a data policy with a masking rule to the policy tag. Grant the shared agent account the Masked Reader role,
roles/bigquerydatapolicy.maskedReader, on the data policy. The account then reads masked values: for exampleNULLwith the Nullify rule, or an empty string for aSTRINGcolumn with the Default masking value rule. - No access. Do not grant the shared agent account the Fine-Grained Reader role,
roles/datacatalog.categoryFineGrainedReader, or the Masked Reader role. A query that selects the column fails with an error. Agent questions that do not use the column still work.
email column of protected_records:
When a policy tag has a data policy, or its taxonomy enforces access control, every account that reads the column needs one of the two roles. Grant Fine-Grained Reader on the policy tag to the connection’s own account, and to people who query with their own Google accounts. Otherwise their dashboards fail on that column too.
See column-level access control and dynamic data masking.
Rows
A row access policy limits the rows that the shared agent account can read. The account still needs Data Viewer on the table:TRUE filter.
Column-level access control, dynamic data masking and row-level security need BigQuery Enterprise or Enterprise Plus edition, or on-demand pricing. See BigQuery editions.
Verify access
Ask an agent to run:BigQuery details
- Connection settings. The shared account replaces credentials; project, dataset, and location come from the project connection.
- Query cost limit. AI agent maximum bytes billed applies regardless of identity. Configure it in the project connection.
- Key reuse. If you switch away from A shared agent account and back without replacing the key, results previously produced by that key become available again. Replace the key if those results must stay inaccessible.
- Query cache. Agent jobs skip the BigQuery query cache.
Databricks
The project connection must use a Databricks SQL warehouse. Unity Catalog applies grants, row filters, and column masks to the identity running each query.The person
Agents use the project’s normal Databricks credentials or the person’s personal warehouse credentials when the project uses them.Shared agent account
Use a service principal with OAuth machine-to-machine authentication.Create the principal and grants
Create a service principal and OAuth secret, add it to the workspace, and grantCAN USE on the connection’s SQL warehouse. Grant access to the tables agents need:
Add and verify the account
In Project settings → Agent identity → Add shared agent account, enter the principal’s application ID as Client ID, enter Client secret, then Test and save. Ask an agent to run:Databricks details
- Connection settings. Host, HTTP path, catalog, schema, and compute come from the project connection.
- Secret expiry. Databricks OAuth secrets expire. Use Replace to rotate the shared principal’s secret before it expires.
- Query cache. Agent queries skip the Databricks result cache.
Athena
Lake Formation grants and data filters on the query’s AWS identity control which data agents can read.The person
Agents use the project’s normal Athena credentials or the person’s personal warehouse credentials when the project uses them.Shared agent account
Use a dedicated AWS identity, Athena workgroup, and S3 results location.Create the identity and grants
- Create the IAM user or role, agent workgroup, and S3 results location. Apply the Permission policy from the project’s agent setup card. For a role, also apply the Role trust policy and allow the caller to assume it. KMS keys and cross-account catalogs need additional permissions. See Athena workgroups.
- As a Lake Formation administrator, apply the Lake Formation grant for each allowed table. Target the user or role ARN, not a session ARN. Use a Filtered table grant to limit rows or columns, and check for broader grants that would override the restriction. See Lake Formation data filters.
Add and verify the account
In Project settings → Agent identity → Add shared agent account, enter Access key ID, Secret access key, Agent workgroup, and S3 results location. Include Session token for assumed-role keys and S3 data location if needed, then Test and save.
GetCallerIdentity and runs a simple query through the agent workgroup. Check that Signs in as shows the intended ARN, then test allowed and denied table access. A successful connection test does not check Lake Formation table grants.
Athena details
- Connection settings. Region, catalog, database, and query settings come from the project connection. The shared agent account supplies its own keys, workgroup, and S3 locations; the connection’s role and credentials do not carry over.
- Key lifetime. Lightdash cannot renew access keys. A dedicated IAM user provides long-lived keys you can rotate; assumed-role keys expire within hours and need manual replacement.
Postgres
Postgres applies grants and row-level security policies to the login role running the query.The person
Agents use the project’s normal Postgres credentials or the person’s personal warehouse credentials when the project uses them.Shared agent account
Use a dedicated login role with a user and password.Create the role and grants
As a superuser or a role withCREATEROLE, create the agent role and grant the schemas it may read:
Limit rows and columns
To limit the rows that agents read, add a row-level security policy for the role. Replace the table and condition placeholders:SELECT grant with a column grant, for example GRANT SELECT (col_a, col_b) ON "<schema>"."<table>" TO "ai_agents";. A table-wide grant still allows every column.
Add and verify the account
In Project settings → Agent identity → Add shared agent account, enter User and Password, then Test and save. Testing checks thatcurrent_user and session_user both match the saved user.
Test allowed and denied table access after confirming the connection works.
Postgres details
- Connection settings. Host, port, database, schema, SSL mode, root certificate, and SSH tunnel come from the project connection. Its client certificates and
rolesetting do not apply to shared agent queries. - Future tables. Run
ALTER DEFAULT PRIVILEGESas each role that creates tables; it affects only that role’s future tables. - Row security bypass. Row-level security does not apply to superusers, to roles with
BYPASSRLS, or to the table owner unless the table hasFORCE ROW LEVEL SECURITY. See Row security policies. - Sign-in failures. Check that the role has
LOGIN, the database exists,pg_hba.confpermits the connection, and the role hasCONNECTon the database.
Redshift
Redshift supports grants, row-level security, and masking policies on the database user running the query.The person
Agents use the project’s normal Redshift credentials or the person’s personal warehouse credentials when the project uses them.Shared agent account
Use a dedicated database user with password authentication.Create the user and grants
As a superuser or a user withCREATE USER, create the agent user and grant the schemas it may read. The password must contain 8–64 ASCII characters, including an uppercase letter, a lowercase letter, and a number, without spaces, quotes, backslashes, slashes, or @.
Limit rows and columns
The setup steps have templates for a row-level security policy and a masking policy. Replace the table, column, type and condition, and match the mask type to the column:Add and verify the account
In Project settings → Agent identity → Add shared agent account, enter User and Password, then Test and save. Testing checks thatcurrent_user and session_user agree and match the saved user, allowing Redshift’s lowercase form for unquoted names.
Test allowed and denied table access.
Redshift details
- Shared account authentication. Shared agent accounts use a user and password even when the project connection uses IAM.
- Connection settings. Host, port, database, schema, SSL settings, and SSH tunnel come from the project connection.
- Inherited privileges. Do not grant the agent user superuser,
IGNORE RLS, orsys:secadminrights. Check inherited andPUBLICgrants as well as direct grants. - Future tables. Repeat
ALTER DEFAULT PRIVILEGESfor each table owner whose future tables agents should read. - Query cache. Agent queries skip the Redshift result cache.
Trino
Trino uses its configured system or connector access control to restrict what the query’s user can read.The person
Agents use the project’s normal Trino credentials or the person’s personal warehouse credentials when the project uses them.Shared agent account
Use a dedicated user with password authentication over HTTPS. Enable password authentication so Trino checks the password.Create the login and restrict access
Trino has noCREATE USER. Ask a Trino admin to add a user to the password file or LDAP, or create a Starburst Galaxy service account with a restricted role.
File-based access control. Set access-control.name=file, and point security.config-file to a rules.json file. The setup steps have a template. It allows read-only access to one catalog, schema and table for the agent user, with an optional row filter and column mask, and denies everything else to that user:
filter and columns fields are optional. If your authenticator maps the login to another user, use the user that Test shows. See File-based access control.
SQL roles and grants. Use this only with a system access control that supports SQL roles and grants:
IN "<catalog>" on CREATE ROLE and on the role grant. Check inherited and public grants.
Add and verify the account
In Project settings → Agent identity → Add shared agent account, enter User and Password, then Test and save. Testing runsSELECT current_user; check the returned user, since Trino user mapping may change the login name.
Test allowed and denied table access.
Trino details
- Shared account authentication. Starburst Galaxy service accounts work with their generated user name and password. Shared accounts do not support JWT, OAuth, Kerberos, or certificate authentication.
- Connection settings. Host, port, scheme, catalog, schema, and source come from the project connection.
- User mapping. Trino can map the login to another user. Base access rules on the user returned by Test.
- Cached results. Agent queries skip Lightdash’s results cache and pre-aggregates. Trino has no result cache setting.
ClickHouse
ClickHouse applies grants and row policies to the user running the query. Shared agent users must be read-only while allowing query tags and session timezone settings.The person
Agents use the project’s normal ClickHouse credentials or the person’s personal warehouse credentials when the project uses them.Shared agent account
Use a dedicated read-only user with password authentication.Create the user and grants
As a user withCREATE USER permission, create the agent user and grant the database or specific tables it may read:
Limit rows
The setup steps have a row policy template. Replace the table and condition before you run it:Add and verify the account
In Project settings → Agent identity → Add shared agent account, enter User and Password, then Test and save. Testing checks thatcurrentUser() exactly matches the saved user, readonly is not 0, the query cache is off, and the required query settings are allowed. If settings are blocked, check the user’s read-only profile. Test allowed and denied table access separately.
ClickHouse details
- Connection settings. Host, port, database, the
securesetting, and timezone come from the project connection. - Read-only settings.
readonly = 2permits the query tags and session timezone that agent queries set. Areadonly = 1user needs a profile that explicitly allows these settings.