Skip to navigation

HTTP Connectors

View as Markdown

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

MethodPathEndpoint reference
GET/platform/extensions/http-connectorsList HTTP connectors
POST/platform/extensions/http-connectorsCreate HTTP connector
GET/platform/extensions/http-connectors/{id}Get HTTP connector
PATCH/platform/extensions/http-connectors/{id}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

FieldTypeRequiredNotes
idstringread-onlyUnique identifier of the HTTP connector, assigned by the server.
namestring✅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_namestringread-onlyLabel shown for the connector in Tool Studio. Read-only; defaults to the name.
descriptionstringread-onlyDescription of the connector as shown in Tool Studio. Read-only.
base_urlstring✅Base URL of the external API that every action path is appended to, for example https://api.example.com/v1. Must use https and a publicly reachable host unless the connector is routed through an on-premise agent.
basic_authBasicAuthSettingsHTTP basic authentication with a username and password.
api_key_authApiKeyAuthSettingsAPI key authentication, sent in a header or query parameter.
oauth2OAuth2SettingsOAuth 2.0 authentication.
jwt_authJwtAuthSettingsJWT bearer authentication signed with a private key you provide.
jwks_authJwksAuthSettingsJWT bearer authentication signed with a key pair that Moveworks generates and rotates.
no_authNoAuthSettingsNo authentication. Set to an empty object to send requests without credentials.
headersarray<RequestParameterSettings>Headers added to every request made through this connector.
query_paramsarray<RequestParameterSettings>Query parameters added to every request made through this connector.
x509_optionsX509OptionsSettingsClient certificate and private key for mutual TLS. Used only when both are set.
csrf_token_optionsCsrfTokenOptionsSettingsSettings for fetching a CSRF token before requests, for systems that require one.
updated_timestringread-onlyWhen the configuration was last updated.
updated_bystringread-onlyWho last updated the configuration.
versionVersion✅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.

FieldTypeRequiredNotes
usernamestringUsername for HTTP basic authentication.
passwordstringPassword for HTTP basic authentication. Secret: always returned masked as *****.

api_key_auth

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

FieldTypeRequiredNotes
api_keystringAPI key issued by the external system. Secret: always returned masked as *****.
query_paramApiKeyQueryParamSettingsSend the key as a query parameter.
headerAuthHeaderSettingsSend 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.

FieldTypeRequiredNotes
token_urlstringToken endpoint URL of the authorization server. Optional for grants that do not exchange a token.
client_credentials_grantOAuth2ClientCredentialsGrantSettingsOAuth 2.0 client credentials grant.
password_grantOAuth2PasswordGrantSettingsOAuth 2.0 resource owner password grant.
refresh_token_grantOAuth2RefreshTokenGrantSettingsOAuth 2.0 refresh token grant, using a refresh token you provide.
jwt_grantJwtAuthSettingsJWT bearer assertion grant, signed with a private key you provide.
authorization_code_grantOAuth2AuthorizationCodeGrantSettingsOAuth 2.0 authorization code grant, where each user signs in to the external system and grants access.
saml_bearer_grantOAuth2SamlBearerGrantSettingsSAML 2.0 bearer assertion grant, using an assertion that Moveworks issues and signs.
jwks_grantJwksAuthSettingsJWT bearer assertion grant, signed with a key pair that Moveworks generates and rotates.
response_optionsOAuth2ResponseOptionsSettingsHow to read the token response when it is not the standard JSON object with access_token and expires_in.
auth_headerAuthHeaderSettingsHow the access token is added to requests. Defaults to the Authorization header with the token as its value.
request_optionsOAuth2RequestOptionsSettingsExtra 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.

FieldTypeRequiredNotes
private_keystringPEM private key used to sign the JWT. Secret: always returned masked as *****.
key_idstringKey ID (kid header) that identifies the private key. Secret: always returned masked as *****.
algorithmenum✅Signing algorithm. One of: ES256, RS256, HS256. One of: ES256, RS256, HS256.
claimsJwtClaimsSettings✅Registered claims of the issued JWT.
headersarray<JwtHeaderSettings>Additional JWT header parameters.
additional_claimsarray<JwtHeaderSettings>Claims to include beyond the registered claims.
assertion_keystringName 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.

FieldTypeRequiredNotes
jwksstringMoveworks-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_hoursanyHours the previous key stays valid after a rotation. 0 uses the default.
rotation_interval_daysanyDays between key rotations. 0 uses the default of 30 days.
claimsJwtClaimsSettings✅Registered claims of the issued JWT.
headersarray<JwtHeaderSettings>Additional JWT header parameters.
additional_claimsarray<JwtHeaderSettings>Claims to include beyond the registered claims.
assertion_keystringName 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.

FieldTypeRequiredNotes

Example create body

{
"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."
}
}