Authenticating with an external application

External applications are configured in Admin > External Apps in UiPath Cloud and use OAuth 2.0 for authentication. They support several authentication scenarios:

• Unattended or automated access without a user login (client credentials grant)
• Third-party integrations that perform their own OAuth flow, such as Copilot Studio or ChatGPT (authorization code grant)
• Desktop or mobile apps where no client secret can be stored safely (authorization code grant with PKCE)

Understanding external application types

When you create an external application, you make two choices that determine how authentication works:

• Whether the app is confidential or non-confidential.
• Whether it uses application scopes or user scopes.

Confidential vs non-confidential apps

	机密	Non-confidential
客户端密码	Generated at creation. Must be stored securely.	Not generated
Who authenticates	The app itself (no user needed), or a user through the app	Only a user through the app
Scope tabs in the UI	Application scope(s) and User scope(s)	User scope(s) only

Use a confidential app when the secret can be stored safely, for backends, servers, and CI/CD pipelines.

Use a non-confidential app for desktop apps, mobile apps, or browser-based single-page apps where a secret cannot be kept safe. Non-confidential apps require PKCE.

Application scopes vs user scopes

The two tabs in the External Apps UI map to fundamentally different OAuth flows:

	Application scopes	User scopes
OAuth grant type	Client credentials (client_credentials)	Authorization code (authorization_code)
身份	The app itself	A human user who logs in through the app
Token sub claim	The app's client_id	The user's ID
Token sub_type claim	service.external	user
How MCP Servers see it	UserType.ExternalApp	UserType.User
Requires user login	否	Yes, the browser redirects to UiPath login
Integration Service 活动	Not supported (no user context)	Supported (user context present)
文件夹访问	App must be explicitly assigned to the folder	The user must have the appropriate role in the folder. The app can be assigned to the folder only if it also has Application scopes; an app with only User scopes cannot be folder-assigned
Available on	Confidential apps only	Both confidential and non-confidential

When you save the external application, the Identity Server sets which grant types the client is allowed to use, based on the scope types you configured:

• Application scopes only → client_credentials is permitted
• User scopes only → authorization_code is permitted
• Both → both are permitted

If you manually request a token from https://cloud.uipath.com/identity_/connect/token, you must explicitly specify grant_type in every token request. Omitting it returns an error. Sending a grant type that was not permitted for the client also fails.

Setting up application scope authentication

Application scopes use the client credentials grant. This is the only authentication method that works without user interaction.

重要提示：

UiPath MCP Servers that expose Integration Service connectors fail when accessed with client credentials. For Integration Service-backed tools, use user scope authentication instead.

先决条件

• You can access Admin > External Apps in UiPath.
• You can manage folder access in Orchestrator.

Create the external application

1. Go to UiPath, select Admin, then External Apps.

2. Select Add Application.

3. Enter a name and keep the Confidential app type.

4. Select the Application scope(s) tab.

   重要提示：

   Add scopes under the Application scope(s) tab, not the User scope(s) tab.

5. Add the following scopes:

   • OR.Execution: required for listing tools. MCP Servers calls the Orchestrator ListReleases API to fetch process metadata when handling tools/list, and that endpoint is authorized with OR.Execution.
   • OR.Jobs: required for executing tools. All MCP Server types that run processes as tools (UiPath, Coded, and Command) call the Orchestrator StartJobs API, which is authorized with OR.Jobs.

6. Select Add, then copy the Client ID and Client secret.

Assign the external app to the folder

1. In Orchestrator, navigate to Tenant > Manage Access, or to the specific folder's access settings.

2. Add the external app with the Automation User role.

   This role includes the MCPServers.View permission required to access MCP Servers.

Authenticate using the external app

Choose one of the following options based on how you want Orchestrator to resolve permissions.

Option A: OR.Default only (recommended for simplicity)

The token carries no explicit API-level scopes. Orchestrator resolves permissions through the roles assigned to the external app in each folder. Cross-folder API calls work without a folder key header. This option requires the external app to have the Automation User role in the target folder.

uipath auth --client-id "<your-client-id>" \
  --client-secret "<your-client-secret>" \
  --base-url "https://cloud.uipath.com/{org}/{tenant}" \
  --scope "OR.Default"

Option B: Explicit scopes

The token carries explicit OR.Execution and OR.Jobs scope claims. Orchestrator validates these scopes directly on each API call. This option requires the X-UIPATH-FolderKey header, but MCP Servers handles this automatically.

uipath auth --client-id "<your-client-id>" \
  --client-secret "<your-client-secret>" \
  --base-url "https://cloud.uipath.com/{org}/{tenant}" \
  --scope "OR.Default OR.Execution OR.Jobs"

结果

The CLI obtains an access token that you can use in the Authorization header for MCP Server requests.

Understanding scope combinations

OR.Default is not a scope you configure in the External Apps UI. It is a special scope you include in the --scope parameter when requesting a token. The scopes you request determine how Orchestrator resolves permissions and how MCP Servers routes API calls.

The MCP flow involves two Orchestrator API calls that require different scopes:

• tools/list: MCP Servers calls odata/Releases/ListReleases to fetch process metadata. The Releases controller requires OR.Execution.
• tools/call: MCP Servers calls odata/Jobs/StartJobs to execute a process. The Jobs controller requires OR.Jobs.

The following table summarizes how different scope combinations behave:

Scopes at token request	Orchestrator permission resolution	X-UIPATH-FolderKey 页眉	MCP Servers behavior
OR.Default only	Folder-level role assignments (for example, Automation User in the target folder)	非必填	Single cross-folder API call
Specific scopes only (for example, OR.Execution OR.Jobs)	Explicit scope claims in the token	Required on every API call	Per-folder API calls (grouped by folder)
OR.Default plus specific scopes	Explicit scope claims (specific scopes take precedence)	Required on every API call	Per-folder API calls (grouped by folder)

Behavior notes:

• Requesting OR.Default only is the simplest setup. Orchestrator checks the roles the external app has been assigned in each folder. The Automation User role covers both Releases and Jobs access.
• Adding specific scopes such as OR.Execution or OR.Jobs (with or without OR.Default) changes how folder resolution works. Orchestrator checks both scope claims and folder role permissions, and access is granted if either check passes. This requires the X-UIPATH-FolderKey header on every API call. MCP Servers handles this automatically by detecting the token's scopes and making per-folder calls when needed.
• Without OR.Default, specific OR.* scopes bypass folder-level role resolution and grant access across all folders within the tenant. The X-UIPATH-FolderKey header is still required for API routing.

Known limitation: GetFoldersForCurrentUser

When running MCP Servers locally with client credentials (uipath run), the Python SDK calls orchestrator_/api/FoldersNavigation/GetFoldersForCurrentUser to resolve the folder path to a folder key. This API does not support client credential authentication, it requires an interactive user token.

To work around this, set the UIPATH_FOLDER_KEY environment variable directly. When this variable is set, the SDK skips the GetFoldersForCurrentUser call entirely:

export UIPATH_FOLDER_KEY="<folder-guid>"
uipath run mcp-server

You can find the folder GUID in the Orchestrator API or in the folder URL.

Common mistake: machine credentials vs external app

Using machine credentials (from Orchestrator > Machines) instead of external application credentials returns invalid_scope errors. Machine credentials are for robot authentication, not for API access.

If you see:

{"error":"invalid_scope","error_description":"..."}

Verify that you are using credentials from Admin > External Apps, not from Orchestrator > Machines.

Setting up user scope authentication

User scopes use the authorization code grant. A user must log in through the external app, and the token carries the user's identity rather than the app's.

Use user scope authentication in the following situations:

• The MCP Server exposes tools backed by Integration Service activities (connectors).
• You are integrating with a third-party client that performs its own OAuth flow (Copilot Studio, ChatGPT).
• You need per-user identity, access control based on who logged in, not which app is calling.

先决条件

• You can access Admin > External Apps in UiPath.
• You can manage folder access in Orchestrator.
• You know the redirect URL of your client application.

Create the external application

1. Go to UiPath, select Admin, then External Apps.

2. Select Add Application.

3. Enter a name and keep the Confidential app type.

4. Select the User scope(s) tab.

   重要提示：

   Add scopes under the User scope(s) tab, not the Application scope(s) tab.

5. Add the following scopes:

   • OR.Execution: required for listing tools.
   • OR.Jobs: required for executing tools (Coded or Command servers).

6. Add a Redirect URL. This is the address that the user's browser is sent to after login. Use the callback URL provided by your client application.

   For Copilot Studio, use a dummy URL initially and update it after the connection is created.

7. Select Add, then copy the Client ID and Client secret.

Configure folder access

Because the external app created above has only User scopes, it cannot be assigned to a folder in Manage Access. Folder access is granted through the user's role; the token inherits the user's permissions, not the app's.

1. In Orchestrator, navigate to Tenant > Manage Access, or to the specific folder's access settings.

2. Assign the user who will log in with the Automation User, Automation Developer, or Folder Administrator role.

   This role determines what the user can do in the folder and must include the MCPServers.View permission required to access MCP Servers.

If the external app also has Application scopes defined, you can additionally assign the app itself to the folder with the Automation User role. This is required only for client credentials flows that do not involve user login.

Run the authorization code flow

The client application initiates the flow.

1. Redirect the user to the authorization endpoint:

   GET https://cloud.uipath.com/identity_/connect/authorize
     ?client_id=<your-client-id>
     &response_type=code
     &redirect_uri=<your-callback-url>
     &scope=OR.Default
   

2. The user logs in through the browser and is redirected back to the callback URL with a code parameter.

3. Exchange the authorization code for a token from your server-side application:

   POST https://cloud.uipath.com/identity_/connect/token
     Content-Type: application/x-www-form-urlencoded
   
     client_id=<your-client-id>
     &client_secret=<your-client-secret>
     &grant_type=authorization_code
     &code=<authorization-code>
     &redirect_uri=<your-callback-url>
   

结果

The token endpoint returns an access token that you can use in the Authorization header for MCP Server requests.

Variant: non-confidential app with PKCE

The same flow works with a non-confidential external app. The differences are summarized below:

	机密	Non-confidential
客户端密码	Included in the token exchange	Not used (no secret exists)
PKCE	可选	必需
Folder assignment	App can be assigned to the folder only if it also has Application scopes defined. With only User scopes, the app does not appear in Manage Access and only the user's folder roles apply	App cannot have Application scopes and never appears in Manage Access; only the user's folder roles apply
Create in UI	Select Confidential	Select Non-confidential

To use this variant:

1. When creating the external application, select Non-confidential instead of Confidential. Only the User scope(s) tab is available. Add OR.Execution, add OR.Jobs for Coded or Command servers, and add the redirect URL.

2. Assign only the user (not the app) to the folder with the appropriate role.

3. Use the following PKCE-based authorization flow:

   # 1. Generate PKCE code verifier and challenge
   code_verifier = <random 64-byte base64url string>
   code_challenge = BASE64URL(SHA256(code_verifier))
   
   # 2. Redirect user to authorize (with PKCE challenge)
   GET https://cloud.uipath.com/identity_/connect/authorize
     ?client_id=<your-client-id>
     &response_type=code
     &redirect_uri=<your-callback-url>
     &scope=OR.Default
     &code_challenge=<code_challenge>
     &code_challenge_method=S256
   
   # 3. Exchange the code for a token (no client_secret; include code_verifier)
   POST https://cloud.uipath.com/identity_/connect/token
     Content-Type: application/x-www-form-urlencoded
   
     client_id=<your-client-id>
     &grant_type=authorization_code
     &code=<authorization-code>
     &redirect_uri=<your-callback-url>
     &code_verifier=<code_verifier>
   

The resulting token is identical to the confidential user-scopes token: sub is the user GUID, sub_type is user, and the audience is UiPath.Orchestrator. MCP Servers treats it the same way as the confidential variant.

Token characteristics (user scopes)

These characteristics apply to both confidential and non-confidential apps using the authorization code flow:

• JWT with sub set to the user's GUID and sub_type set to user.
• Audience: UiPath.Orchestrator.
• MCP Servers resolves the token as user identity — at the MCP Servers layer, the token follows the same code path as interactive login.
• Folder key routing does not apply (single cross-folder Orchestrator call).
• Integration Service activities work (user context is present).
• Refresh token: returned when offline_access is included in the scope parameter; not returned without it. Refresh token lifetime is 60 days.

Connecting Copilot Studio to a UiPath MCP Server

Use this procedure to connect a Microsoft Copilot Studio agent to a UiPath MCP Server using OAuth 2.0 manual authentication.

先决条件

• You can manage external applications.
• You can manage folder access in Orchestrator.
• You can configure connections in Copilot Studio.

步骤

1. In UiPath, go to Admin > External Apps and select Add Application.

2. Set the app type to Confidential.

3. Under Resources, add Orchestrator API Access with the OR.Execution scope, and add it as both an Application scope and a User scope.

   If the MCP Server is Coded or Command type, also add OR.Jobs under both scopes.

   Adding the scope under the Application scope(s) tab is what makes step 6 work; an app with only User scopes cannot be assigned to a folder in Manage Access.

4. Enter a dummy redirect URL for now (for example, https://cloud.uipath.com).

5. Save the application, then copy the Client ID and Client secret.

6. In Orchestrator, assign the external app to the folder containing the MCP Server with the Automation User role. This works because the app was given Application scopes in step 3; an app with only User scopes cannot be folder-assigned. Also assign the tenant role Allow to be Automation User.

7. In Copilot Studio, add the MCP Server URL with OAuth 2.0 Manual authentication, using the following values:

   • Client ID: the value copied in step 5.
   • Client secret: the value copied in step 5.
   • Authorization URL: https://cloud.uipath.com/identity_/connect/authorize
   • Token URL: https://cloud.uipath.com/identity_/connect/token
   • Refresh URL: https://cloud.uipath.com/identity_/connect/token
   • Scope: OR.Default

8. Select Create in Copilot Studio. Copilot Studio generates a redirect URL, the field is greyed out before creation.

9. Copy the generated redirect URL and add it to the external app's Redirect URLs in UiPath Admin > External Apps.

10. Return to Copilot Studio and select Connect.

结果

Copilot Studio is connected to the UiPath MCP Server. The user logs in through the OAuth flow when the agent accesses MCP tools.

Connecting ChatGPT to a UiPath MCP Server

Use this procedure for new or unpublished ChatGPT apps where Dynamic Client Registration (DCR) does not work.

ChatGPT changed its redirect URIs from /connector_platform_oauth_redirect to /connector/oauth/{callback_id}. Already published apps still work with DCR. New or unpublished apps require manual OAuth setup.

先决条件

• You can manage external applications.
• You can create apps in ChatGPT.

Get the callback URL from ChatGPT

1. Go to ChatGPT, select your profile, then select Apps, then Create app.
2. Enter the app name, description, and the MCP Server URL from UiPath.
3. Select Advanced settings.
4. Under Registration method, change from DCR to UserDefined OAuth Client.
5. Copy the Callback URL (https://chatgpt.com/connector/oauth/{callback_id}).
6. Keep this browser tab open.

Create the external application in UiPath

1. Go to Admin > External Apps and select Add Application.

2. Select Confidential as the app type.

3. Add OR.Execution, OR.Jobs, and OR.Folders under both the Application scope(s) and User scope(s) tabs.

   Adding the scopes under the Application scope(s) tab is what allows the next step (folder assignment) to work; an app with only User scopes cannot be assigned to a folder in Manage Access.

4. In the Redirect URL field, paste the callback URL copied from ChatGPT.

5. Save the application, then copy the Client ID and Client secret.

Assign the external app to the folder

1. In Orchestrator, open the folder containing the MCP Server.
2. Navigate to Manage Access > Assign.
3. Add the external app with the Automation User role.

Configure ChatGPT

1. Return to the ChatGPT browser tab.
2. Enter the OAuth Client ID and Client secret copied from the external app.
3. Under Client registration > Token endpoint auth method, select client_secret_basic.
4. Under Scopes > Default scopes, deactivate any existing default scopes.
5. Under Scopes > Base scopes, add OR.Default.
6. 选择“创建”。

结果

ChatGPT is connected to the UiPath MCP Server. Users authenticate through the manual OAuth flow when the app accesses MCP tools.

Behavior of OR.Default

OR.Default is referenced in both application-scope and user-scope flows, but it behaves differently in each context:

Context	行为
Application scopes, in the --scope parameter at token request	Controls how Orchestrator resolves permissions. When OR.Default is the only scope, Orchestrator uses folder role assignments instead of explicit scope claims. Check Understanding scope combinations.
User scopes, in the scope parameter of the authorize request	Used as the scope parameter in the authorize request. At the Orchestrator level, it enables a permissive authorization mode where access is granted if either the scope check or the user's folder role permissions pass. MCP Servers does not use OR.Default for user-scoped tokens, it always makes single cross-folder calls regardless of which scopes the token carries.

In neither case is OR.Default a scope you configure in the External Apps UI. It only appears in the scope parameter at token or authorization request time.