> This page is for 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. # OAuth 2.0 Authorization Code Use the OAuth 2.0 Authorization Code Grant when an integration needs to access a connected system with each user's permissions. The user signs in and grants access, then Moveworks exchanges an authorization code for tokens that represent that user. This guide applies to HTTP connectors used by plugins and by custom MCP servers that do not support Dynamic Client Registration (DCR). ## How Authorization Code Works The authorization server handles sign-in and consent. Moveworks receives an authorization code, exchanges it for tokens, and uses the access token when the integration calls the connected system. The diagram shows the recommended flow with PKCE using a SHA256 challenge. ```mermaid sequenceDiagram actor U as User participant M as Moveworks participant A as Authorization server participant S as Connected system M->>M: Create a verifier and SHA256 challenge M->>A: Send authorization request and challenge A->>U: Ask the user to sign in and consent U-->>A: Approve access A-->>M: Return an authorization code M->>A: Exchange the code and verifier A-->>M: Return access and refresh tokens M->>S: Send a request with the user's access token ``` Proof Key for Code Exchange (PKCE) protects the authorization code from interception. The client secret authenticates the connector to the authorization server. These controls solve different problems, and a provider may require both. ## Before You Start Confirm that: * You can create HTTP connectors in Tool Studio. * You can register an OAuth application with the connected system's authorization provider. * The provider supports the Authorization Code Grant. * You have the system's base URL, authorization URL, token URL, required scopes, and any provider-specific parameters. ## Register the Callback URL Register the callback URL for your Moveworks data center in the provider's OAuth application. Replace `` with your Moveworks organization name. | Data center | Callback URL | | -------------------------- | ---------------------------------------------------------------- | | United States (default) | `https://.moveworks.com/auth/oauthCallback` | | Canada | `https://.am-ca-central.moveworks.com/auth/oauthCallback` | | EU | `https://.am-eu-central.moveworks.com/auth/oauthCallback` | | Australia and Asia Pacific | `https://.am-ap-southeast.moveworks.com/auth/oauthCallback` | | Government Secure Cloud | `https://.moveworksgov.com/auth/oauthCallback` | | Japan | `https://.jp.moveworks.com/auth/oauthCallback` | | UK | `https://.uk.moveworks.com/auth/oauthCallback` | | US Prod 4 | `https://.prod4.us.moveworks.com/auth/oauthCallback` | | US Prod 3 | `https://.prod3.us.moveworks.com/auth/oauthCallback` | To find your organization name, open Tool Studio and copy the base URL. Your organization name is the subdomain. For example, the organization name in `https://acme.moveworks.com` is `acme`. > **Moveworks adds the callback URL** > > Moveworks automatically includes your organization-specific callback URL in the authorization request. Do not add a custom `redirect_uri` query parameter unless Moveworks instructs you to do so. ## Configure the HTTP Connector #### Create an HTTP connector In Tool Studio, open **HTTP Connectors** and create a connector. ![HTTP Connectors page in Tool Studio.](https://files.readme.io/56360d974404f7631f476f1713afd138a54328b99b1b13872147e187f6b24b57-CleanShot_2025-09-25_at_10.39.212x.png)![Control for creating an HTTP connector in Tool Studio.](https://files.readme.io/27362415f5db9914d31fb8d1d9184fcbfd1eacb6a7ace1a8c720d147dd7c1d59-CleanShot_2025-09-25_at_10.40.392x.png) #### Enter the connector information Complete the connector fields: | Field | What to enter | Why it matters | | ----------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------- | | **Connector Name** | A stable internal name. You cannot change it after you create the connector. | Identifies the connector in Tool Studio. | | **Display Name** | The system name users recognize, such as **Workday** or **Salesforce**. | Appears to users during authorization. | | **Display Description** | A short description of the access the integration requests. | Helps users understand what they are authorizing. | | **Base URL** | The base URL for the connected API or MCP server. | Sets the destination for requests that use the connector. | #### Choose Authorization Code Grant Set **Auth Config** to **OAuth2**, then set **OAuth2 Grant Type** to **Authorization Code Grant**. ![HTTP connector authentication settings with OAuth2 and Authorization Code Grant selected.](https://files.readme.io/a0838d73f02d31ccb50ccfd0370fa3c522b9f575a7781fae6d5e0b329077ad16-CleanShot_2025-09-25_at_10.41.412x.png) #### Enter the required OAuth settings Use the values from the authorization provider: | Field | What to enter | Why it matters | | ---------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------- | | **Authorization URL** | The provider's authorization endpoint. | Sends users to the provider to sign in and grant consent. | | **Client ID** | The client ID from the OAuth application you registered. | Identifies the application requesting access. | | **Client Secret** | The client secret from the registered OAuth application. | Authenticates the connector when it exchanges the authorization code. | | **Authorization Code Grant Scope** | A space-separated list of the scopes the integration needs. | Limits the data and operations the integration can access. | | **OAuth2 Token URL** | The provider's token endpoint. | Exchanges the authorization code for access and refresh tokens. | #### Configure PKCE when required Follow the authorization provider's PKCE requirements. > **Required for OAuth-protected MCP servers** > > Select **PKCE using SHA256 code challenge** for an OAuth-protected MCP server. Do not select the plain code verifier for this connection path. ![Authorization Code Grant PKCE Algorithm with PKCE using SHA256 code challenge selected.](/_fern-img/5246c7f23e1126bda56c28ed688bbaf9a832e0a13c4b648c4fde7b6ae51e9ff1.webp) #### Save the connector Review the values, then save the connector. If you edit it later, saved secret values appear blank. Leave a secret field blank to keep the current value, or enter a new value to replace it. > **Parameters Moveworks Adds Automatically** > > Moveworks adds `response_type=code`, your organization-specific `redirect_uri`, `access_type=offline`, and a randomly generated `state` value to the authorization request. Do not add these values under additional request data or query parameters. ## Configure Recommended and Advanced Settings Configure token revocation when the provider supports it: * **Revoke URL**: Enter the provider's token revocation endpoint. * **Instructions URL**: Enter a user-facing page that explains how to revoke access when automatic revocation fails. * **Revocation token key**: Use the request field expected by the provider. The default is `token`. * **Revocation authentication and headers**: Match the provider's requirements. #### Configure provider-specific advanced settings Some providers require additional authorization query parameters, token-request data, headers, certificates, or custom token formatting. Configure these fields only when the provider's documentation or Moveworks requires them. Common examples include: * An `audience` or `prompt` authorization query parameter. * Additional token-request data sent as `application/x-www-form-urlencoded`. * A custom authorization header name or token value pattern. * Additional request headers or common query parameters. * X.509 certificates, private keys, or a CSRF endpoint. Do not manually add `state`, `response_type`, `redirect_uri`, or `access_type`. Moveworks adds them automatically. ## Validate the Connector Authorize the connector, then validate the path that uses it. #### Plugin Open an action, event, path, or query that uses the connector. Test the request in the HTTP editor and confirm that the connected system returns the expected response with the test user's permissions. #### MCP Workspace Return to [Connect and Manage Servers](/tool-studio/mcp-workspace/connect-and-manage-servers), select the connector for the custom server, and generate a token. Select **Preview Tools** and confirm that the server returns the expected tool inventory. If validation fails, check the callback URL, authorization and token URLs, client credentials, scopes, PKCE selection, and any provider-specific parameters. ## What Users Experience When an integration needs user authorization, Moveworks checks the required connectors before it runs: 1. If the user has a valid token, the integration continues. 2. If the user has not authorized the connector or the token is invalid, the assistant asks the user to grant access. 3. The user opens the authorization link and signs in with the connected system. 4. The user grants consent and returns to the assistant. 5. Moveworks resumes the original request automatically. ![A user granting an integration access from the Moveworks assistant and returning after authorization.](https://files.readme.io/79f7956b769784ce537c2eed3d412bc91744b964dd9fb25ea18e07e22fcaf6d6-hackathon-demo-asana-v02-loop.gif) Moveworks preserves the original request for 30 minutes while the user completes authorization. After 30 minutes, the user must make the request again. If an integration requires authorization for multiple connectors, the assistant presents them together and shows the user's progress. The integration runs after the user authorizes every required connector. ### Limitations [Notify actions](https://docs.moveworks.com/tool-studio/actions/compound-actions/notify) (for example, approval workflows that send a message and wait for a response from another user) are not supported with preflight check. If your plugin uses a notify action, the preflight check and auto-restart behavior described above will not apply. This is a known limitation. > **My Moveworks SSO Is Required** > > Add every user who needs to authorize an integration to My Moveworks SSO. This gives users access to the connections page where they grant consent. It does not give them access to admin or developer products without the corresponding roles. Use the [SSO documentation](/platform-management/sso) to configure access.