This guide explains how to connect Viz Flowics to JSON or Atom/RSS endpoints and feeds that require authentication. If your data provider requires a username and password, API key, or Bearer token to access their endpoint or feed, this is the setup you need.

Note: If you previously accessed endpoints using credentials embedded in the URL (e.g., https://user:pass@url), that method is no longer supported as it exposes credentials to Control users. This guide covers the secure alternative.

Supported authentication methods

HTTP Basic (RFC 7617): Username and password
HTTP Bearer: Token-based authentication
API Keys: Custom header, query parameter, or cookie

All secret values (passwords, bearer tokens, and API keys) are stored securely in the Viz Flowics secrets vault and are never exposed to Control users or visible in the Graphics Editor.

Note: OAuth 2.0 authentication is not currently supported.

Terminology

Before you start, it helps to understand these three terms:

Credential Account: The saved authentication configuration you create in External Integrations
Credential Descriptor: The authentication method: Basic, Bearer, or API Key
Security Scheme: The Credential Account selected inside the connector settings

Step 1 — Create a Credential Account

In Viz Flowics, go to Data Connectors → External Integrations
Select Generic (JSON/RSS)
Click New account

[Screenshot: New account form showing Name, Authority, and Credential Descriptor fields]

Enter a Name for the account
Enter the Authority: this is the domain of your endpoint or feed URL

Example:
Endpoint URL: https://api.provider.com/feed
Authority: api.provider.com

✅ Correct: api.provider.com
❌ Incorrect: provider.com

Select a Credential Descriptor and fill in the required fields:
- HTTP Basic authentication → enter username and password
- HTTP Bearer authentication → enter your token
- API Keys → enter a key name, choose location (header, query parameter, or cookie), and enter the value
Click Save

Important: The Authority field is used to match credentials to the correct endpoint URL. Only credentials whose authority matches the URL domain will appear in the Security Scheme dropdown. Make sure the authority matches the exact domain of your URL, including any subdomain (e.g., api.provider.com, not provider.com).

Step 2 — Configure the Data Connector

Open your graphic in the Graphics Editor
In the Data Connectors panel, add or select a JSON Get or Atom/RSS connector
Enter your endpoint or feed URL
In the Security Scheme field, select the Credential Account you created in Step 1
Save and run the connector

Tip: If the Security Scheme only shows "None", no Credential Account exists for that URL's authority. Go back to Step 1 and make sure the Authority matches your URL's domain exactly.

How each authentication method works

HTTP Basic

Sends username and password as:
Authorization: Basic <encoded credentials>

HTTP Bearer

Sends your token as:
Authorization: Bearer <token>

API Keys

Sends a custom key-value pair via the location you choose. For example, using a header with name X-API-Key and value abc123 sends:
X-API-Key: abc123

Example: Using a Bearer Token

If your API requires the following header: Authorization: Bearer abc123

Go to Data Connectors → External Integrations → Generic (JSON/RSS)
Click New account and select HTTP Bearer authentication
Enter your token (abc123) and save
In your connector settings, select that account in the Security Scheme field

Viz Flowics will automatically include the Authorization header in every request to that endpoint.

Common issues

Security Scheme dropdown only shows "None"
No Credential Account exists for that URL's authority. Create one in External Integrations using the correct domain, including any subdomain.

Endpoint returns 401 Unauthorized after setup
Verify the credentials are correct and that the Authority in your account matches the exact domain of the endpoint URL.

Connector worked previously, but now returns 401 Unauthorized
The credentials may have expired or been revoked. Common causes:

Bearer token has expired
API key was rotated or revoked by the provider
The password was changed

Update the Credential Account in External Integrations with the new credentials.

Endpoint returns 403 Forbidden after setup
The server accepted the authentication credentials but denied access to the resource. Verify that the authenticated account has permission to access the requested endpoint.

Credentials are not appearing in the Security Scheme dropdown
The authority must match the domain of the endpoint URL exactly. Check for typos or subdomain mismatches (e.g., api.provider.com vs provider.com).