Configure the Connector

A connector represents one external system’s base URL and authentication configuration. It does not define an API operation. HTTP actions inherit the connector and add their own endpoint path, method, request fields, and response contract.

Understand the URL Boundary

Connector base URL                         HTTP action endpoint
https://marketplace.moveworks.com     +    /api/purple-suite/crm/accounts

Together they form the request URL:

https://marketplace.moveworks.com/api/purple-suite/crm/accounts

Use one connector for compatible actions against the same system and identity. Create another connector when the base URL, tenant, credentials, or identity model differs.

Step 1: Choose the Execution Identity

Shared Application or Service Identity

Delegated User Identity

Every request uses the same downstream identity.

Common mechanisms include:

API key
Bearer token
OAuth 2.0 Client Credentials
Basic authentication

Use this model for backend automation and operations that do not need the downstream system to enforce each user’s permissions.

Do Not Confuse the Identity Model with the Protocol

OAuth does not always mean user consent. Authorization Code usually represents a user, while Client Credentials represents an application. A JWT bearer assertion can represent an application or a delegated subject depending on the provider. Confirm the exact identity semantics, flow, and scopes.

Step 2: Prepare the Downstream System

Complete the provider-side configuration first:

Create or approve the service account or OAuth application.
Assign the minimum roles and scopes required by the planned actions.
Register callback URLs for delegated OAuth when required.
Configure IP allowlists or network rules.
Create non-production test data.
Document token rotation, revocation, ownership, and expiration.

The connector cannot grant a permission the downstream system has not granted.

Step 3: Configure the HTTP Connector

In Agent Studio, create an HTTP connector and configure:

Connection Name

stringRequired

Use a recognizable system, tenant, environment, and identity name.

Description

stringRequired

State which downstream system, environment, and execution identity the connector represents.

Base URL

URLRequired

Use the stable scheme and host, plus any path prefix shared by every compatible action.

Authentication Type

connector authenticationRequired

Select the mechanism supported by the provider and your chosen identity model.

Authentication Fields

secret and non-secret valuesRequired

Enter the token URL, client ID, secret, API key pattern, claims, scopes, or other provider-specific fields.

Step 4: Configure Moveworks Asset Access

Downstream API permissions and Moveworks asset permissions solve different problems:

Layer	Controls
Downstream system	Which records and operations the credential can access
Connector access	Which Moveworks developers and plugins may use the connection
Action access	Who may use or manage the executable operation
Plugin launch configuration	Which end users may discover and run the capability

Grant Use access through the complete plugin → action → connector dependency chain.

Step 5: Validate the Connector

Use a safe, read-only endpoint when possible:

Verify successful authentication.
Verify the request reaches the intended tenant and environment.
Confirm the response contains only records the chosen identity should access.
Test an expired or invalid credential.
Test a caller without required Moveworks asset access.
Record the expected renewal or consent experience.

Connector Reuse Is a Security Decision

Reuse a connector only when every consuming action should share its destination and identity. A narrowly scoped connector is easier to audit than a powerful credential reused across unrelated capabilities.

Build Along: Configure the PurpleSuite Connector

Complete PurpleSuite Setup, then create the shared connector used by every action in this course:

PurpleSuite end-to-end call trace

Follow one live feature request through the same three API calls and Agent Studio contracts in every chapter.

Shared connector

https://marketplace.moveworks.com

Every API action

Connector adds Bearer PAT. Action adds X-Instance-ID.

Provide one authenticated route to PurpleSuite

The same connector supplies the base URL and PAT for every API call. Each action adds its endpoint and instance header.

List candidatesAPI callDynamic resolver + List action

GET /api/purple-suite/community/feature_requests
$filter: currentStatus ne 'Planned'
$select: id,name,currentStatus,productArea
$top: 10

Receives

Resolver invocation and optional search context

Returns

{ data: FeatureRequest[], nextCursor, total }

How it fits

This is the first real API call. The resolver uses the response list, so the assistant can select only records that PurpleSuite returned.

Successful run: actual API call ledger

1GET/api/purple-suite/community/feature_requestsDynamic resolver retrieves live candidates

2PATCH/api/purple-suite/community/feature_requests/{id}Compound action updates the selected record

3GET/api/purple-suite/community/feature_requests/{id}Compound action verifies the stored result

Use a record returned by your own PurpleSuite instance. Save its original status before the write and restore it after mutation testing when appropriate.

Field	Value
Connection name	`PurpleSuite development`
Description	`Shared development connection for the PurpleSuite mock enterprise APIs`
Base URL	`https://marketplace.moveworks.com`
Authentication type	API key
Header	`Authorization`
Header value pattern	`Bearer %s`
Action header	`X-Instance-ID: <your instance ID>`

Store the PAT in the connector. Add the instance ID to the actions that require it, not to the connector base URL.

Validate the connection with this safe read against the Community API:

GET /api/purple-suite/community/feature_requests
$select: id,name,currentStatus
$top: 1
X-Instance-ID: <your instance ID>

The connector adds the stored Authorization: Bearer <PAT> header. The action adds X-Instance-ID. Your checkpoint is a 200 response with the { data, nextCursor, total } envelope and a connector that no unrelated production plugin can use.

Temporary Development Credential

PurpleSuite credentials expire. Treat this connector as a development asset, record its expiration, and never copy the PAT into a request example or documentation field.

Deep Dives

Next, build focused actions.