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
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
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 uses IAM access keys and signs requests with AWS Signature Version 4. Like GCP, the proxy handles signing — the sandbox receives placeholder environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION) and the proxy substitutes real credentials at request time. Setup steps:
  1. In the AWS IAM console, create an IAM user or role with the permissions your workflow needs, and generate an access key.
  2. In TextQL, select Amazon Web Services from the template list.
  3. Enter your Access Key ID, Secret Access Key, and optionally a Default Region (defaults to us-east-1).
  4. Click Test Connection.

​
Manual Configuration

To add a custom API, select Custom / Other at the top of the Add API Access menu.
Custom API Access configuration form
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
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

​
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
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 must use API Connectors > Secrets.
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
Python cell using API Connector with TQL_AUTH_TOKEN header

​
Disabling Legacy Secrets

Once you’re confident everything works with API Connectors:
  1. Go to Settings > Features & Tools
  2. Toggle off Environment Variables
Settings page with Environment Variables toggle highlighted
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: 
Look through my chats in the past 30 days, you have access to a usage connector.
Check the python cells in the chats that use secrets.

​
Need Help?

Contact support@textql.com.