Connector hosts, secrets and data access

An ANY API connector built with the AI assistant reaches outside in three ways: it calls the API's hosts, it signs in with secrets you provide, and a data access grant can let it read rows from a Lake or Warehouse object. People decide all three boundaries, and the assistant works within them. This page covers how each boundary behaves; the building itself is on Build an ANY API connector, and the wizard that creates the connector is on Connect any API.

Approve the hosts a connector may call

• A recipe can call only the hosts you approve. While one of its hosts is unapproved, the connector form shows an "Unapproved hosts" warning, and the recipe cannot be confirmed until each host is approved or revoked.
• Host entries are exact: lower case, no scheme and no path, with the port only when it is not the default, such as api.example.com:8443. Only a host the recipe itself uses can be approved; the assistant cannot add one of its own.
• Changing the connection settings recomputes the host list, and a host that changed needs a fresh approval.
• Approving a host is a person's decision. The assistant asks for it, but never approves a host on its own, and it does not ask you to approve one it merely saw in a response body or on a documentation page.
• When the connector has data access grants, the approval is a card that only an administrator can decide, and it waits in every mode, even when the assistant's other changes apply automatically. The reason: the new host will also receive the granted columns.
• While no host has ever been approved yet, the assistant can still research the API with read-only GET requests. That probe window closes permanently at the first approval; after it, every request goes to an approved host.
• Some addresses can never be approved: loopback, link-local and cloud-metadata addresses, and anything internal to the platform, are refused, and so is a host whose name is built from a secret. A refusal is final: the assistant does not look for another route, another encoding or another tool to reach it.
• The Hosts list in the connector shows what is approved, and you can revoke a host there. The panels around it are on Hosts, streams and data access.

Enter secrets in the connection form

• The assistant never asks for a secret value in the chat. When a stream needs a credential, it asks you to enter the value in the connection form under Connection and continues once the field shows as set.
• Secret fields show as masked password fields.
• Placeholders never count as a value: REPLACE_ME, TODO, xxx and test are not accepted, and a missing credential is never filled with one.
• In the recipe, a secret appears only as a reference, {{ config['key'] }}, exactly where a request needs it. The assistant never writes a value into the recipe or into the connector's public settings.
• The assistant can tell you which secret fields are set, but never a value: only the platform itself can read values.
• If you paste a credential into the chat, the assistant will not repeat it or put it into the recipe; enter it in the form instead. If it warns you that a credential reached it anyway, treat that value as exposed and replace it.

Grant access to table rows

A data access grant lets the recipe read the rows of one Lake or Warehouse object, so the API can be asked about data that the connector could not otherwise see.

• Setting one up is a person's decision, made in the connector's Data access section. The assistant can raise the request, which waits as a card for an administrator, but it never grants anything itself.
• The recipe reads the granted rows as a stream named grant_<name> and uses them to drive its requests. The grant stream itself is never loaded into the Lake on its own.
• Only an Active grant feeds a load. A grant that breaks stops its loads until it resolves again.
• A grant-driven stream reads its rows in one of two ways, never both: in batches (rows grouped 100 at a time, with duplicates removed) or row by row as an incremental stream on the grant's date column.
• Before such a run, the assistant estimates its cost from the row count and the batch, and it warns you above 10,000 requests or about an hour per run.
• The row cap is a guard: a run that would read more rows than the cap fails before the first API request, so nothing is sent.
• Personal data is protected in one direction: columns marked as personal data travel as platform tokens, never as raw values. Every other granted column is sent exactly as it is, so grant only the columns the API needs. Personal data in AI work has the full token rules.
• During the build, a sample of a grant-driven stream reads at most five unfiltered rows: it proves the shape, not the data. A grant preview is for administrators.
• The grant's life cycle, from confirmation to revoking one, is on Data access grants.

Questions, answered

Can the assistant call my API before I approve a host?

Partly. Until the first host has ever been approved, it can research the API with read-only GET requests. That window closes for good at the first approval; from then on, every request goes to an approved host.

Why does a host need approval again after I change the connection settings?

Because approvals match exact entries. Changing the settings recomputes the host list, and a host that changed is treated as new: approve it again. Entries are lower case, without a scheme or path, and carry the port only when it is not the default, like api.example.com:8443.

Who approves a host?

A person, through the product; the assistant never approves one on its own. When the connector has data access grants, the decision is a card that only an administrator can confirm, and it waits in every mode, because the new host will also receive the granted columns.

Why can an address that works on my network not be approved?

Addresses like loopback, link-local and cloud-metadata ones, and anything internal to the platform, are refused by design. The refusal is final: the assistant does not look for another route, another encoding or another tool to reach them.

Where do I enter the secrets the connector needs?

In the connection form, under Connection, in the field the assistant names. It continues once the field shows as set, and it can see which fields are set, never the values themselves.

Can I give the assistant my API key in the chat instead?

No. The assistant never asks for a secret value in the chat, and it will not repeat or use one you paste; enter it in the connection form. If it warns you that a credential reached it anyway, treat that value as exposed and replace it.

Will a value like REPLACE_ME do for now?

No. Placeholders such as REPLACE_ME, TODO, xxx and test are never accepted as a secret, and a missing credential is never filled with one.

What do the granted rows look like to the recipe?

They arrive as a stream named grant_<name>, which the recipe uses to drive its requests. Only an Active grant feeds a load; a broken grant stops its loads until it resolves again, and the grant stream is never loaded into the Lake on its own.

How expensive is a grant-driven run?

It depends on the rows and the batch: the requests per run are the row count divided by the batch. The assistant estimates this and warns you above 10,000 requests or about an hour per run. Rows are read in batches or row by row, never both.

What happens if a granted table is bigger than its row cap?

The run fails before it sends anything, so nothing is requested from the API.

Does a grant send personal data to my API?

Columns marked as personal data are sent as platform tokens, never as raw values. Every other granted column is sent as it is, so grant only the columns the API needs; the full rules are on Personal data in AI work.