Agent Access and Security

Control which warehouse identity an AI agent uses for each member.

An Agent Principal is a warehouse identity that an AI agent can use when it runs a query. Each principal has its own credentials and permissions. The warehouse role or grants for that identity determine which data the member can access through the agent.

Agent Principals are available from an agent's Access page. Organization owners and admins can manage them when the feature is enabled.

How principals work

Every agent with a configured destination starts with a Destination Principal. This principal uses the identity configured for the destination and acts as the default for the agent.

You can add more principals when different members need different warehouse permissions. Principals belong to the destination, so agents that use the same destination share its list of principals.

A member can use a principal in one of two ways:

  • Inherited — The member uses the agent's current default principal. This is the default.
  • Assigned — The member uses a specific principal, even if the agent's default changes later.

Changing the default affects members who inherit the default. It does not affect members with an assigned principal.

Open the Access page

  1. Open the AI agent.
  2. Select Access.

The Access page contains a list of principals and a list of members who can use the agent.

Add a principal

  1. On the Access page, select Add principal.
  2. Enter a name that helps your team identify the identity, such as Finance read-only.
  3. Enter the identity details for your warehouse.
  4. Select Add principal.

For Snowflake, provide the user, role, and private key. You can optionally provide a warehouse and a private key passphrase. If you leave the warehouse blank, the principal uses the warehouse configured for the destination.

For Databricks, provide the OAuth client ID and OAuth client secret.

After adding a principal, use Actions > Test connection to check that it can reach the warehouse.

Set the default principal

  1. On the Access page, open Actions for a principal.
  2. Select Set as default.
  3. Confirm the change.

Members who inherit the default will use the new principal the next time they use the agent. Members with an assigned principal continue to use their assigned identity.

Assign a principal to a member

  1. Find the member in the Members table.
  2. Open the principal selector in that member's row.
  3. Select a principal.

The member now uses that principal instead of inheriting the default. To restore the default behavior, open the selector and choose Inherit default.

Delete a principal

Open Actions for the principal and select Delete. A principal cannot be deleted while it is the destination identity, the default for an agent, or assigned to a member. Move those agents or members to another principal first.

Deleting a principal removes its stored credentials. The credentials cannot be recovered, so they must be entered again if you recreate the principal.