> This page is for API Reference & Tools.

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

# HTTP Connectors

> Create, read and update HTTP connectors through the Moveworks Configuration API.

`platform.extensions.http-connectors`

An HTTP connector holds the base URL and credentials for one external API. HTTP actions and MCP servers call that API through it, so create the connector first.

To learn what HTTP connectors do, see [HTTP Connectors](/tool-studio/connectors/http-connectors) in the Tool Studio docs.

* **Endpoint:** `/platform/extensions/http-connectors`  |  **Methods:** GET, PATCH, POST
* **Request shape:** fields go at the top level of the JSON body, with no `resource` wrapper. The item's `id` goes in the URL for reads and updates, not in the body.
* **Updates:** a JSON merge-patch with `version: {num, change_description}` from your last read. Lists of objects merge row by row, so read first and send the whole list when you remove or reorder rows. See [Tool Studio](/api-reference/configuration-api/tool-studio/overview#how-updates-work).
* **References:** Referenced by HTTP actions and MCP servers through `connector_id`, which takes the connector's `id`.

### Endpoints

All paths are relative to `https://api.moveworks.ai/configurations/v1alpha1`. Each endpoint page lists the request and response schema, an example, and the errors it can return.

| Method  | Path                                        | Endpoint reference                                                                                          |
| ------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `GET`   | `/platform/extensions/http-connectors`      | [List HTTP connectors](/api-reference/configuration-api/tool-studio/http-connectors/list-http-connectors)   |
| `POST`  | `/platform/extensions/http-connectors`      | [Create HTTP connector](/api-reference/configuration-api/tool-studio/http-connectors/create-http-connector) |
| `GET`   | `/platform/extensions/http-connectors/{id}` | [Get HTTP connector](/api-reference/configuration-api/tool-studio/http-connectors/get-http-connector)       |
| `PATCH` | `/platform/extensions/http-connectors/{id}` | [Update HTTP connector](/api-reference/configuration-api/tool-studio/http-connectors/update-http-connector) |

### Rules the API checks

* `name` is unique in your organization and can't be changed after creation.
* `base_url` is the scheme, host and any fixed path prefix, with no trailing `/` and no query string. Put query parameters for every request in `query_params`.
* Set exactly one auth block: `no_auth`, `basic_auth`, `api_key_auth`, `oauth2`, `jwt_auth` or `jwks_auth`.
* Secrets (`password`, `api_key`, `client_secret`, `private_key`) are sent in plain text and come back redacted. You can't read them back.

### Fields

| Field                | Type                             | Required  | Notes                                                                                                                                                                                                                                              |
| -------------------- | -------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | string                           | read-only | Unique identifier of the HTTP connector, assigned by the server.                                                                                                                                                                                   |
| `name`               | string                           | ✅         | Unique name of the connector, used by HTTP actions to refer to it. 2-64 letters, digits or underscores, starting with a letter. Cannot be changed, or reused after deletion.                                                                       |
| `display_name`       | string                           | read-only | Label shown for the connector in Tool Studio. Read-only; defaults to the name.                                                                                                                                                                     |
| `description`        | string                           | read-only | Description of the connector as shown in Tool Studio. Read-only.                                                                                                                                                                                   |
| `base_url`           | string                           | ✅         | Base URL of the external API that every action path is appended to, for example [https://api.example.com/v1](https://api.example.com/v1). Must use https and a publicly reachable host unless the connector is routed through an on-premise agent. |
| `basic_auth`         | BasicAuthSettings                |           | HTTP basic authentication with a username and password.                                                                                                                                                                                            |
| `api_key_auth`       | ApiKeyAuthSettings               |           | API key authentication, sent in a header or query parameter.                                                                                                                                                                                       |
| `oauth2`             | OAuth2Settings                   |           | OAuth 2.0 authentication.                                                                                                                                                                                                                          |
| `jwt_auth`           | JwtAuthSettings                  |           | JWT bearer authentication signed with a private key you provide.                                                                                                                                                                                   |
| `jwks_auth`          | JwksAuthSettings                 |           | JWT bearer authentication signed with a key pair that Moveworks generates and rotates.                                                                                                                                                             |
| `no_auth`            | NoAuthSettings                   |           | No authentication. Set to an empty object to send requests without credentials.                                                                                                                                                                    |
| `headers`            | array\<RequestParameterSettings> |           | Headers added to every request made through this connector.                                                                                                                                                                                        |
| `query_params`       | array\<RequestParameterSettings> |           | Query parameters added to every request made through this connector.                                                                                                                                                                               |
| `x509_options`       | X509OptionsSettings              |           | Client certificate and private key for mutual TLS. Used only when both are set.                                                                                                                                                                    |
| `csrf_token_options` | CsrfTokenOptionsSettings         |           | Settings for fetching a CSRF token before requests, for systems that require one.                                                                                                                                                                  |
| `updated_time`       | string                           | read-only | When the configuration was last updated.                                                                                                                                                                                                           |
| `updated_by`         | string                           | read-only | Who last updated the configuration.                                                                                                                                                                                                                |
| `version`            | Version                          | ✅         | Document version. On update, send back the num from your last read.                                                                                                                                                                                |

Set at most one of `basic_auth`, `api_key_auth`, `oauth2`, `jwt_auth`, `jwks_auth`, `no_auth`.

### Variants (6, pick one)

**`basic_auth`**

HTTP basic authentication with a username and password.

| Field      | Type   | Required | Notes                                                                                 |
| ---------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `username` | string |          | Username for HTTP basic authentication.                                               |
| `password` | string |          | Password for HTTP basic authentication. Secret: always returned masked as \*\*\*\*\*. |

**`api_key_auth`**

API key authentication, sent in a header or query parameter.

| Field         | Type                     | Required | Notes                                                                                                             |
| ------------- | ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `api_key`     | string                   |          | API key issued by the external system. Secret: always returned masked as \*\*\*\*\*.                              |
| `query_param` | ApiKeyQueryParamSettings |          | Send the key as a query parameter.                                                                                |
| `header`      | AuthHeaderSettings       |          | Send the key in a request header. Defaults to the Authorization header with the value Bearer followed by the key. |

In `api_key_auth`, set at most one of `query_param`, `header`.

**`oauth2`**

OAuth 2.0 authentication.

| Field                      | Type                                 | Required | Notes                                                                                                        |
| -------------------------- | ------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| `token_url`                | string                               |          | Token endpoint URL of the authorization server. Optional for grants that do not exchange a token.            |
| `client_credentials_grant` | OAuth2ClientCredentialsGrantSettings |          | OAuth 2.0 client credentials grant.                                                                          |
| `password_grant`           | OAuth2PasswordGrantSettings          |          | OAuth 2.0 resource owner password grant.                                                                     |
| `refresh_token_grant`      | OAuth2RefreshTokenGrantSettings      |          | OAuth 2.0 refresh token grant, using a refresh token you provide.                                            |
| `jwt_grant`                | JwtAuthSettings                      |          | JWT bearer assertion grant, signed with a private key you provide.                                           |
| `authorization_code_grant` | OAuth2AuthorizationCodeGrantSettings |          | OAuth 2.0 authorization code grant, where each user signs in to the external system and grants access.       |
| `saml_bearer_grant`        | OAuth2SamlBearerGrantSettings        |          | SAML 2.0 bearer assertion grant, using an assertion that Moveworks issues and signs.                         |
| `jwks_grant`               | JwksAuthSettings                     |          | JWT bearer assertion grant, signed with a key pair that Moveworks generates and rotates.                     |
| `response_options`         | OAuth2ResponseOptionsSettings        |          | How to read the token response when it is not the standard JSON object with access_token and expires_in.     |
| `auth_header`              | AuthHeaderSettings                   |          | How the access token is added to requests. Defaults to the Authorization header with the token as its value. |
| `request_options`          | OAuth2RequestOptionsSettings         |          | Extra data to send on the token request beyond the standard grant fields.                                    |

In `oauth2`, set at most one of `client_credentials_grant`, `password_grant`, `refresh_token_grant`, `jwt_grant`, `authorization_code_grant`, `saml_bearer_grant`, `jwks_grant`.

**`jwt_auth`**

JWT bearer authentication signed with a private key you provide.

| Field               | Type                      | Required | Notes                                                                                              |
| ------------------- | ------------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `private_key`       | string                    |          | PEM private key used to sign the JWT. Secret: always returned masked as \*\*\*\*\*.                |
| `key_id`            | string                    |          | Key ID (kid header) that identifies the private key. Secret: always returned masked as \*\*\*\*\*. |
| `algorithm`         | enum                      | ✅        | Signing algorithm. One of: ES256, RS256, HS256. One of: `ES256`, `RS256`, `HS256`.                 |
| `claims`            | JwtClaimsSettings         | ✅        | Registered claims of the issued JWT.                                                               |
| `headers`           | array\<JwtHeaderSettings> |          | Additional JWT header parameters.                                                                  |
| `additional_claims` | array\<JwtHeaderSettings> |          | Claims to include beyond the registered claims.                                                    |
| `assertion_key`     | string                    |          | Name of the request field the signed JWT is sent under. Defaults to assertion.                     |

**`jwks_auth`**

JWT bearer authentication signed with a key pair that Moveworks generates and rotates.

| Field                         | Type                      | Required | Notes                                                                                                                                                                                                                                       |
| ----------------------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jwks`                        | string                    |          | Moveworks-generated key pair this connector signs with. Leave empty to generate a new key pair; send back the value from your last read to keep the current key. ID of an existing JwksSecret; not available through the Configuration API. |
| `rotation_grace_period_hours` | any                       |          | Hours the previous key stays valid after a rotation. 0 uses the default.                                                                                                                                                                    |
| `rotation_interval_days`      | any                       |          | Days between key rotations. 0 uses the default of 30 days.                                                                                                                                                                                  |
| `claims`                      | JwtClaimsSettings         | ✅        | Registered claims of the issued JWT.                                                                                                                                                                                                        |
| `headers`                     | array\<JwtHeaderSettings> |          | Additional JWT header parameters.                                                                                                                                                                                                           |
| `additional_claims`           | array\<JwtHeaderSettings> |          | Claims to include beyond the registered claims.                                                                                                                                                                                             |
| `assertion_key`               | string                    |          | Name of the request field the signed JWT is sent under. Defaults to assertion.                                                                                                                                                              |

**`no_auth`**

No authentication. Set to an empty object to send requests without credentials.

| Field | Type | Required | Notes |
| ----- | ---- | -------- | ----- |

### Example create body

```json
{
  "name": "erp_production",
  "base_url": "https://erp.example.com",
  "api_key_auth": {
    "api_key": "the-erp-api-key",
    "header": {
      "key": "X-API-Key",
      "value_pattern": "%s"
    }
  },
  "headers": [
    {
      "key": "Accept",
      "value": "application/json"
    }
  ],
  "version": {
    "change_description": "Initial version."
  }
}
```