> This page is for Agent Studio.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server.

# 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

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

Together they form the request URL:

```text
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

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.

#### Delegated User Identity

Each user authorizes Moveworks to act as that user.

OAuth 2.0 Authorization Code is the common pattern. The connector stores and refreshes each user's token after consent.

Use this model when the downstream system must enforce the user's own record access, roles, or audit identity.

> **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:

1. Create or approve the service account or OAuth application.
2. Assign the minimum roles and scopes required by the planned actions.
3. Register callback URLs for delegated OAuth when required.
4. Configure IP allowlists or network rules.
5. Create non-production test data.
6. 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`** `string` — required

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

---

**`Description`** `string` — required

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

---

**`Base URL`** `URL` — required

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

---

**`Authentication Type`** `connector authentication` — required

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

---

**`Authentication Fields`** `secret and non-secret values` — required

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](/agent-studio/quickstart-guide/purple-suite-setup), then create the shared connector used by every action in this course:

| 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:

```text
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

* [Connectors](/agent-studio/connectors)
* [HTTP Connectors](/agent-studio/connectors/http-connectors)
* [OAuth 2.0 Authorization Code](/agent-studio/connectors/http-connectors/oauth-20-authorization-code)
* [OAuth 2.0 Client Credentials](/agent-studio/connectors/http-connectors/oauth-20-client-credentials)
* [API Key Authentication](/agent-studio/connectors/http-connectors/api-key-auth)
* [Connector Access Control](/agent-studio/access-control/connectors-and-access)

Next, [build focused actions](/agent-studio/guides/plugin-building-masterclass/build-focused-actions).