Skip to main content
API Connectors enable you to connect any web API in a secure way. You can find a list of accessible APIs in the API tab of the Connectors page. Ana can access these APIs from the Python sandbox — no additional toggles are required in your chat.
API Connectors page

The API Connectors page showing configured connectors

If the API tab is not present, external API access has been disabled for your organization. Contact your admin to enable it.
To use an API, your admin must first whitelist the domain it is served on. Since most APIs require authentication, you can enter a token that will be used for requests to that API. Ana can use these APIs without ever having access to your token directly. A user can access a domain from the sandbox when they have access to at least one connector associated with this domain. Every kind of API access (with and without authentication) is configured on the APIs connector page. To whitelist a domain, click the + New API Access button. It will create an API connector without associated auth data. Both token-based authentication and OAuth are supported.

​
Creating an API Connector from a Template

For the most frequently used APIs, TextQL offers pre-configured templates — you only need to enter your token and test the connection.
  1. Navigate to the Connectors page and open the Add API menu.
  2. Select your API from the list of common providers.
  3. Enter your credentials and click Test Connection.
Add API Access modal showing available templates

Pick from a template or use Custom for manual configuration

If the test is not successful, verify your credentials or try a manual setup by expanding the Advanced Options.

​
Provider-Specific Setup

Most API templates work by entering a token and clicking Test Connection. A few providers use a different authentication model where the proxy handles credential injection automatically — you supply the credentials once, and the proxy signs every outgoing request on your behalf.

​
Google Cloud (GCP)

The GCP connector uses a service account key rather than a static bearer token. The proxy intercepts outgoing requests, performs the JWT-based token exchange with Google’s OAuth endpoint, and injects a short-lived access token — your raw credentials are never exposed to the sandbox. Setup steps:
  1. In the Google Cloud Console, create or select a service account with the IAM roles your workflow needs.
  2. Under the service account’s Keys tab, click Add Key > Create new key and choose JSON. Download the key file.
  3. In TextQL, open the Connectors page, click + New API Access, and select Google Cloud from the template list.
  4. Paste the entire contents of the downloaded JSON key file into the Service Account JSON field.
  5. Optionally enter your Project ID.
  6. Click Test Connection to verify the credentials are valid.
The service account JSON is stored encrypted. The sandbox receives a placeholder environment variable (GOOGLE_SERVICE_ACCOUNT_JSON) — the actual key is never passed through.
The GCP connector whitelists *.googleapis.com. If your workflow calls a Google API on a different host, add it as an additional domain in the connector’s Advanced Options.

​
Amazon Web Services (AWS)

The AWS connector supports IAM access keys or an IAM role and signs requests with AWS Signature Version 4. The proxy handles signing, and the sandbox receives placeholder credentials. Real access keys and temporary role credentials stay on the server. Setup steps:
  1. Choose how to authenticate:
    • Access keys: create an IAM user with the permissions your workflow needs and generate an access key. To assume a role with those keys, also configure the user’s sts:AssumeRole permission and the target role’s trust policy.
    • Keyless IAM role (self-hosted): ask your deployment operator to configure the allowlist and trust policy described below. No access keys are needed.
  2. In TextQL, select Amazon Web Services from the template list.
  3. Choose an Authentication method: Access keys, IAM role (no access keys), or IAM role with access keys. Fill in the fields shown for that method. The External ID field is available when assuming a role with access keys and is only needed if the trust policy requires it.
  4. Set Default Region to the region your workflow uses (defaults to us-east-1). Role assumption and Test Connection use that region’s STS endpoint, including its AWS partition.
  5. Click Test Connection.
Keyless setup: the proxy assumes the target role from the deployment’s own AWS identity (IRSA, EKS Pod Identity, or an instance profile). This is off unless the operator adds <organization ID>=<role ARN> to the AWS_API_ROLE_ALLOWLIST environment variable (comma-separated) on the compute service. The proxy always sends textql-<your organization ID> as the External ID in this mode; you do not need to enter it in the form. The target role’s trust policy must allow the deployment’s IAM role to call sts:AssumeRole and require that sts:ExternalId. Without the condition, another organization allowlisted for the same role could assume it. For EKS Pod Identity with session tags enabled, the target role also needs a separate sts:TagSession trust statement for the deployment’s IAM role, without the sts:ExternalId condition. See AWS’s target role trust policy example. Deployments without internet egress need a regional STS VPC endpoint reachable by the compute service. Role credentials are cached and refreshed when needed. The cache has a fixed size and evicts older entries as connector configurations change.

​
Manual Configuration

To add a custom API, select Custom / Other at the top of the Add API Access menu.
Custom API Access configuration form

The custom API connector form with host, auth, and header configuration

Description (optional) Provide a description of what this API connector does and what capabilities the token has. Domains (Hosts) Specify the hosts to whitelist as a comma-separated list. Matching is strict on protocol, domain, and port to prevent token leakage. By default, only HTTPS traffic on port 443 is permitted. To whitelist all subdomains of a domain, use *.domain. Authentication Check your API’s documentation for the required format. Add all necessary header fields or URL query parameters. Include any token prefixes (e.g., Bearer) directly in the value field, as you are setting raw header values. Expiry Date (optional) Set an expiry date to prevent Ana from attempting to use expired tokens.
Test your API connection before saving. You can add multiple connectors for the same domain — for example, if you have tokens with different permission levels. Use the sharing menu to control which users can access each connector.

​
Editing a Connector

To edit an existing API connector, click the Edit button from the connector list. When editing:
  • Credentials are preserved by default. If you leave an auth field blank (or it shows a redacted placeholder), the existing credential is kept. You only need to re-enter a value if you want to change it.
  • Provider-managed auth headers are not shown in the manual headers list. For template-based connectors, the authentication header (e.g. Authorization) is managed through the dedicated auth fields, not the custom headers table. This is expected behavior.

​
OAuth APIs

OAuth is supported for most pre-configured API providers. You can also make a custom connector with OAuth. To set up an OAuth connector:
  1. Select a supported provider template (or custom) in the Add API menu.
  2. Create an OAuth app in your provider’s interface and paste the credentials into the form.
  3. Choose U2M OAuth or Per Member OAuth as the authentication method.
    • Per Org OAuth means all people using this connector will connect to the same account at the provider.
    • Per Member OAuth means each user can connect their individual account.
  4. You can specify a grant type, which controls how the OAuth token exchange is performed. For provider templates, you usually want to keep the default setting.
  5. Specify the required scopes. Depending on the provider, you might have to allow these scopes for your OAuth app in the provider interface first.
  6. Connect your account and test the connection.
For per-member OAuth connectors, each user accesses the API with their individual account. When a user first triggers an OAuth API connector (i.e., when Ana calls this API from the Python sandbox), they will be prompted to authenticate and connect their account. In shared chats, the chat owner’s account is used. If other users want to use their per-member connectors in shared chats, the owner has to consent each time.

​
Domain Whitelisting

Some workflows hit endpoints that don’t need authentication (public APIs, documentation sites, etc.). These domains still need to be explicitly whitelisted. To add one, click + New API Access and select Domain Whitelist.
Add API Access modal with Domain Whitelist option highlighted

Select Domain Whitelist from the Add API Access modal

Once legacy Environment Variables (Secrets) are turned off, the Python sandbox enforces domain whitelisting: any domain that isn’t whitelisted and doesn’t have an API Connector will be blocked. While Secrets are still enabled, domain whitelisting is not enforced — the sandbox allows outbound requests to any domain. Other connectors (Tableau, PowerBI, MCP servers, Web Search, etc.) are unaffected by these rules and can still reach the internet through their own configured channels.
Blocked request to a non-whitelisted domain

A request to arxiv.org fails because the domain wasn't whitelisted

​
Migrating to API Connectors

Read this section even if you have not previously used secrets, but have used APIs without secrets-based authentication.
TextQL is deprecating the Secrets feature (accessible from a separate tab on the Connectors page, if your organization has not yet migrated). We are replacing it with API Connectors to improve security. Migration steps:
  1. Identify which external APIs you use or plan to use in chats.
  2. Add one API Connector for each domain (use a template if available, or add it as a custom connector).
  3. Configure sharing permissions for each connector.
  4. For each existing secret, edit the corresponding API Connector and paste the token into the appropriate field. If it is a manually configured connector, include any required token prefix (e.g., Bearer).
If you want to allow some users to access an API without authentication, add a domain whitelist entry instead of a full connector.
Environment Variables tab showing existing secrets

The Env Vars tab where legacy secrets are stored

During the migration you can keep credentials in both Secrets and API Connectors at the same time. To force Ana to prefer the new system, add this to the end of your prompts:
You can tell which system Ana is using by looking at the Python cells. If you see SECRETS["XYZ_SOURCE"], that’s the old system. If you see a header with TQL_AUTH_TOKEN followed by a unique ID, that’s API Connectors.
Python cell using legacy SECRETS environment variable

Old approach — SECRETS-based authentication

Python cell using API Connector with TQL_AUTH_TOKEN header

New approach — API Connector authentication via TQL_AUTH_TOKEN

​
Disabling Legacy Secrets

Once you’re confident everything works with API Connectors:
  1. Go to Settings → Capabilities
  2. Toggle off Environment Variables
Settings page with Environment Variables toggle highlighted

Toggle off Environment Variables in Settings to disable legacy secrets

After this, the Python sandbox can only make outbound requests to domains covered by API Connectors or your whitelist. Other tools (BI connectors, MCP servers, Web Search) are unaffected. All previously configured secrets stop working.
Before flipping this switch, confirm that you’ve:
  1. Tested all workflows that rely on external API access
  2. Whitelisted any unauthenticated domains your workflows need
  3. Verified Ana is using API Connectors (not Secrets) in all critical workflows
Domain whitelisting is only enforced once Environment Variables (Secrets) are turned off. While Secrets are still enabled, the Python sandbox allows outbound requests to any domain — the whitelist has no effect. This is expected during migration, but aim to disable Secrets once you’ve finished testing so that whitelisting kicks in.

​
Troubleshooting

​
GCP or AWS test connection fails

For GCP, confirm the service account JSON is pasted in full (including the outer { } braces) and that the service account has at least one IAM role assigned. The test calls oauth2.googleapis.com/tokeninfo — if your network blocks that endpoint, the test will fail even with valid credentials. For AWS, double-check that the Access Key ID and Secret Access Key belong to an active IAM user or role. If you see a SignatureDoesNotMatch error, the secret key was likely truncated during copy-paste.

​
API request fails after disabling secrets

Most likely a domain that needs whitelisting. Re-enable secrets temporarily, figure out which domain the failing workflow hits, add it to your whitelist, then disable secrets again.

​
Ana is still using Secrets instead of API Connectors

Append You must use API Connectors > Secrets. to your prompt to force Ana to prefer API Connectors during the transition.

​
Not sure which secrets are actively used

Ask Ana with the Usage Connector:

​
Need Help?

Contact support@textql.com.