- Release Notes
- Overview
- Getting Started
- Marketplace Vendors
- Marketplace Customers
- Publishing Guidelines
- Publishing Guidelines for Ready-to-go Automations
- Publishing Guidelines for Solution Accelerators
- Publishing Guidelines for Integration Service Connectors
- Security & IP Protection
- Other UiPath Listings
- Node-RED
- Setup
- Teams
- Microsoft Teams Scope
- Create Team
- Create Team From Group
- Get Team
- Get Teams
- Channels
- Create Channel
- Delete Channel
- Get Channel
- Get Channels
- Update Channel
- Chats
- Get Chat
- Get Chats
- Get Chat Members
- Messages
- Get Message
- Get Messages
- Get Message Replies
- Reply To Message
- Send Message
- Events
- Create Event
- Delete Event
- Get Event
- Get Events
- Users
- Get User Presence
- How It Works
- Technical References
- Get Started
- About
- Setup
- Technical References
- Azure Form Recognizer Scope
- Activities
- Analyze Form
- Analyze Form Async
- Get Analyze Form Result
- Analyze Receipt
- Analyze Receipt Async
- Get Analyze Receipt Result
- Analyze Layout
- Analyze Layout Async
- Get Analyze Layout Result
- Train Model
- Get Models
- Get Model Keys
- Get Model Info
- Delete Model
- Connectors
- How to Create Activities
- Build Your Integration
How to Authenticate
Authenticating with UiPath Orchestrator API is dependent on the type of Orchestrator instance that you're connecting to. There are two types of Orchestrator instances, both of which use a bearer token for authentication: Cloud Orchestrator and On-premise Orchestrator.
From an authentication perspective, there are two main differences between the instance types. The first is the endpoint that you send requests to and the second is the required inputs for the authentication requests.
The table below shows the different endpoints and inputs for each instance type, as well as, links to the applicable API documentation.
Cloud Orchestrator |
On-premise Orchestrator | |
---|---|---|
Endpoint |
https://account.uipath.com/oauth/token | https://{{orchestrator-url}}/api/Account/Authenticate |
Inputs |
|
|
Request/Response |
Both instance types include an optional Folder input. Folders enable you to maintain fine-grained control over automations and their intrinsic entities, and personnel across the entire organization. There are two types of folders available in Orchestrator: Classic and Modern. Classic folders are enabled by default while the Modern folders functionality must be enabled by the Host or Tenant administrator.
If a user enters a Folder value, you need to retrieve the OrganizationUnitId of the folder. This identifier must be included in the Header of all subsequent API requests after authentication is completed.
How do I get a folder OrganizationUnitId value?
To retrieve the OrganizationUnitId you must have the Folder Name and follow the API requests listed below.
-
Using the Folder Name as your input parameter, send a GET request to the GetFolders endpoint (e.g.,
{{base url}}/odata/Folders?$filter=FullyQualifiedName eq '{{FolderName}}'
).When the username of the user is known, you can also retrieve the OrganizationUnitId of the folder and verify its permissions in a single request. For more information see, below.
How do I verify folder permissions?
There are multiple ways to verify whether a user has permission to access a specific folder. How you verify permissions is dependent on whether or not you have the username (not the email) of the user.
Option 1 - username unknown
This option applies to Cloud Orchestrator instances, as well as, On-premise Orchestrator instances where only the user email is known.
- Using the entered credentials,
retrieve the UserId of the user by sending a GET request to the GetCurrentUser endpoint (e.g.,
{{base url}}/Users/Users_GetCurrentUser
). - After retrieving the GET response
that containts the UserId, send a GET request to the GetUsersForFolder endpoint using the Folder Name and
UserId as your input parameters (e.g.,
{{base url}}/Folders/UiPath.Server.Configuration.OData.GetUsersForFolder(key={{*FolderOrganizationUnitId*}},includeInherited=true)?$filter=Id eq{{userId}}
).
Option 2 - username known
This option applies to instances where username is known (typically this will only apply to the On-premise Orchestrator instances).
-
Using the entered username, send a GET request to the GetAllRolesForUserByUsernameAndSkipAndTake endpoint (e.g.,
{{base url}}/Folders/UiPath.Server.Configuration.OData.GetAllRolesForUser(username='{{username}}',skip=0,take=0)
).- The response includes all of the folders the user has permission to access. By parsing the response, you can verify that it includes the Folder Name the user entered and/or the OrganizationUnitId that was retrieved in a previous request.
- The benefit of using this option is that you can get the OrganizationUnitId of the folder and verify permissions in a single request.
A connector can have multiple authenticated connections to the same or different Orchestrator tenant. The purpose of multiple connections is to enable more than one user to access and use the implemented connector features (e.g., start a job, add Queue items) without sharing their Orchestrator credentials.
This section provides links to example connector user interfaces and the corresponding Orchestrator API requests for each input field.