Skip to content

Connectors

The Connectors page in the application allows users to define and manage OAuth connectors. These connectors are used to generate Bearer tokens for authenticating with external APIs, enabling secure communication between your AI agents and third-party services.

Overview

The page provides functionalities to:

  • Add new connectors.
  • List existing connectors, filtered by the selected agent.
  • Edit existing connectors.
  • Delete connectors.

Add Connector

Adding a New Connector

To add a new connector:

  1. Navigate to the Connectors page.
  2. Expand the "New Connector" section.
  3. A form will appear with the following fields:
    • Name: (Text Input) A unique and descriptive name for the connector (e.g., "MyServiceOAuth", "JourneyIDConnector"). This name acts like a variable and cannot contain spaces.
    • Active: (Toggle) Activates or deactivates the connector. Default is True (active).
    • Header as Payload: (Toggle) Specifies if the client ID and secret should be sent in the header (typically as a Basic Auth string) or as part of the request body payload. Default is False (sent in payload).
    • Agent(s): (Multiselect) Select one or more agents that will be able to use this connector.
    • Connector URL: (Text Input) The URL endpoint of the OAuth token provider (e.g., https://auth.example.com/oauth/token).
    • Grant Type: (Text Input) The OAuth grant type (e.g., "client_credentials"). This can also be a special type for cloud storage, like gcs_service_account or aws_iam. See the Quick Help section for details.
    • Content Type: (Selectbox) The content type of the token request. Options: application/x-www-form-urlencoded, application/json.
    • Scope: (Text Input, Optional) The scope of the access request for OAuth 2.0. This is a space-separated list of permissions the application is requesting (e.g., "read:user write:repo").
    • Client ID: (Text Input) The client ID provided by the OAuth service.
    • Client Secret: (Password Input) The client secret provided by the OAuth service or json key or secret for cloud file storage.
    • Service Account Email (optional): The GCP service account email to grant bucket access to when using this connector. Will be used for building RAG Stores.
  4. Click the "Create Connector" button.
  5. Upon submission, the system stores the connector configuration.

Listing Connectors

Existing connectors are listed under the "Connectors" subheader.

  • Filtering: The list is automatically filtered to display connectors associated with the globally selected agent (if an agent is selected in the application's main navigation/sidebar).
  • Display: Each connector is shown in an expandable section, displaying its name, status (✅ for active, ❌ for inactive), and associated agents.
  • Details: Expanding a connector's section reveals:
  • Client ID
  • URL
  • Grant Type
  • Content Type
  • Each connector entry has "Edit" and "Delete" buttons.

Editing a Connector

To edit an existing connector:

  1. Click the "Edit" button next to the desired connector in the list.
  2. The "Edit [Connector Name]" form will appear, pre-filled with the connector's current information.
  3. All fields from the "Add Connector" form are available for modification.
    • The "Client Secret" will be displayed as a password input field.
  4. Click "Save Changes" to update the connector or "Cancel" to discard changes and hide the edit form.

Deleting a Connector

To delete a connector:

  1. Click the "Delete" button next to the desired connector in the list.
  2. Confirm the deletion when prompted (though the code doesn't explicitly show a confirmation dialog, it's standard practice). The connector will be permanently removed from the database.

How Connectors are Used

Connectors defined on this page can be selected when configuring items on the APIs page or the Files page.

For APIs (OAuth 2.0)

When an API call is made that uses one of these connectors for authentication:

  • If "Header as Payload" is False (default): The system makes a POST request to the "Connector URL" with "Client ID", "Client Secret", and "Grant Type" in the request body (formatted according to "Content Type") to obtain a Bearer token.
  • If "Header as Payload" is True: The system makes a POST request with "Client ID" and "Client Secret" typically encoded in an Authorization: Basic <base64_encoded_credentials> header, and "Grant Type" in the body, to obtain a Bearer token.
  • The obtained Bearer token is then automatically included in the Authorization header of the actual API call being made by the agent.

For Files (Cloud Storage)

When a File operation uses a connector for Google Cloud Storage or AWS S3, the connector provides the necessary credentials directly, rather than fetching a token.

  • GCS: The connector provides the service account key from the Client Secret field.
  • S3: The connector provides the AWS Access Key and Secret from the Client ID and Client Secret fields.

This documentation should provide a good understanding of how to use the Connectors page.

Quick Help - Connector Configuration

Connectors are used to securely store credentials and obtain authentication tokens (like OAuth Bearer tokens) for external services.

Common OAuth Grant Types

When setting up a connector for a service that uses OAuth 2.0, you'll often use one of the following Grant Type values:

  • client_credentials: This is a common grant type for server-to-server communication where the application is authenticating itself, not on behalf of a user. You will typically provide a Client ID and Client Secret.
  • Basic Auth: If the service uses Basic Authentication, you can enable the Header as Payload toggle. This will encode the Client ID and Client Secret into a standard Authorization: Basic ... header.

Cloud Storage Connectors (for Files)

To allow agents to read and write files from cloud storage or for use in Stores building a RAG with Vertext AI, configure connectors with the following special grant types:

For Google Cloud Storage (GCS):

  • Grant Type: Set this to gcs_service_account.
  • Client ID: Can be left blank or used for the GCS Project ID.
  • Client Secret: Paste the entire JSON content of your GCS service account key file here.

Note on GCP Permissions: Ensure that the service account associated with the provided key has the necessary permissions you desire. Use Storage Object Admin (roles/storage.objectAdmin) for managing files inside and existing buckets. If you want PinionAI to also create buckets, use Storage Admin (roles/storage.admin) for read/write access on the specific GCS buckets you intend to use. You can also specify a service account email in the "Service Account Email" field to grant bucket access to that specific service account when using this connector.

For AWS S3:

  • Grant Type: Set this to aws_iam.
  • Client ID: Your AWS Access Key ID.
  • Client Secret: Your AWS Secret Access Key.

Note on Default Credentials: If no connector is specified for a GCS or S3 file operation, the system will attempt to use Application Default Credentials (for GCS) or environment variables/IAM roles (for S3). This is ideal for services running directly on GCP or AWS.