Authenticating

The authentication system for the UiPath Orchestrator API uses a bearer token for local users and NTLM authentication for directory users.

Note: By default, the bearer token expires after 30 minutes.

Important:

The instructions on this page apply only for the on-premises Orchestrator API. Basic authentication for API is not supported for Automation Cloud Orchestrator tenants.

If you are using the Orchestrator service in Automation Cloud, use the instructions in Consuming Cloud API instead.

Local User Authentication Via a Bearer Token

1. Make a POST request to the {OrchestratorURL}/api/account/authenticate endpoint with your Orchestrator login credentials, as in the example below.
   POST {OrchestratorURL}/api/account/authenticate

   Request headers:

   Key	Value
   Authorization	Bearer

   Request body:

   {
       "tenancyName" : "Documentation",
       "usernameOrEmailAddress" : "Documentation",
       "password" : "DocumentationAPItest"
   }

   Response code: 200 OK

   Response body:

   {
       "result": "Rr22VaC0D6MkzFShb0gKqaw3vYUJSMmo4jJWk5crDYtSbZkxPFuOC9ApMEnug2q8WxEGPkVwmNoaSXzxOBwia1Ecrldg5BUXXErU_VNOo_yt7X_GDF8sMTyErSqO9Gfe7RSinIueQU6Q_axlY4jDnCP5r2LHrAJVdyM8Tg9x3WHnR8MOgeOl290uTsSOM1ezGG-OmFarRqFUPiN2-iE_mo1KNW-9AmT87-p1-ZYTusLaGyTS9jKVGtRhMjjB0l9VyOFvINhjptq8zotCo5cOOVWJeuvh-307ZdcUWHxkFTwoGDS_DpC4D7JrKfp4oWeSkA0SSy95RfzT8KRTmsJGQV0k8VD6HE3aa_7c-FGrCDjRVtDSkTgpQcQFrIXD8kT4P52a_18doKaSB-asQ8scYe_o73fCL4VtqLDb2ZWlAwEChVmorcFjbXnejxuAubjoKaoJH10gzc5_IiCPI8pM-Zm09Z5D1ljsNjWJ_LrmOR3dijuuKUGvCDtyCCCU_JrPRxmdYSXZmHHx_3joAux0-A",
       "targetUrl": null,
       "success": true,
       "error": null,
       "unAuthorizedRequest": false,
       "__abp": true
   }

2. Copy the string in the result parameter of the HTTP response to the Clipboard. This represents the bearer token and can be used in all future requests as follows:
   • As an Authorization header with the Bearer xxxxxxxxxxxxx value, where xxxxxxxxxxxxx represents the string previously copied;
   • If your API testing tool supports it, select the bearer token authorization type and input the string previously copied.

Domain User Authentication Via NTLM Authentication

Important: To authenticate your requests using Windows credentials you need to use an API client that supports NTLM authentication, such as Postman.

1. Make a request to the desired endpoint specifying your Windows credentials in the dedicated API client. To change an NTLM auth header in Postman, navigate to the Auth tab, set the Type to NTLM Authentication, and fill in the Username and Password fields.
   
   

   

   
   
2. If your user exists in multiple tenants, specify the exact one using the X-UIPATH-TenantName header otherwise the request is performed in the first tenant the user has been provisioned in. The following example illustrates a GET request to the {OrchestratorURL}/odata/Processes endpoint in the Finance tenant.
   GET {OrchestratorURL}/odata/Processes

   Request headers:

   Key	Value
   Authorization	Bearer
   X-UIPATH-TenantName	The name of the tenant. For example, "Finance".

   Response code: 200 OK

   Response body:

   {
       "@odata.context": "{OrchestratorURL}/odata/$metadata#Processes",
       "@odata.count": 2,
       "value": [
           {
               "IsActive": false,
               "SupportsMultipleEntryPoints": false,
               "RequiresUserInteraction": true,
               "Title": null,
               "Version": "1.0.6981.35861",
               "Key": "QueueItemsProcessing:1.0.6981.35861",
               "Description": "Process items from an Orchestrator queue.",
               "Published": "2020-10-17T14:22:11.0566667Z",
               "IsLatestVersion": false,
               "OldVersion": null,
               "ReleaseNotes": null,
               "Authors": "petrina.smith",
               "ProjectType": "Undefined",
               "Id": "QueueItemsProcessing",
               "Arguments": {
                   "Input": "[{\"name\":\"argument1\",\"type\":\"System.Int32, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\",\"required\":false,\"hasDefault\":true},{\"name\":\"argument2\",\"type\":\"System.Int32, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\",\"required\":false,\"hasDefault\":false},{\"name\":\"argument3\",\"type\":\"System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\",\"required\":false,\"hasDefault\":true}]",
                   "Output": null
               }
           },
           {
               "IsActive": false,
               "SupportsMultipleEntryPoints": false,
               "RequiresUserInteraction": false,
               "Title": "TestingSequence",
               "Version": "4.0.6",
               "Key": "TestingSequence:4.0.6",
               "Description": "Blank Process",
               "Published": "2020-10-17T13:04:06.6766667Z",
               "IsLatestVersion": false,
               "OldVersion": null,
               "ReleaseNotes": "Invoke WF Action Generator",
               "Authors": "petrina.smith",
               "ProjectType": "Process",
               "Id": "TestingSequence",
               "Arguments": {
                   "Input": "[{\"name\":\"Name\",\"type\":\"System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\",\"required\":false,\"hasDefault\":false},{\"name\":\"Email\",\"type\":\"System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\",\"required\":false,\"hasDefault\":false},{\"name\":\"Product\",\"type\":\"System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\",\"required\":false,\"hasDefault\":false}]",
                   "Output": null
               }
           }
       ]
   }

Accessing Swagger

If you are using Swagger to try our API, just log in to your Orchestrator instance in a separate tab.

The Orchestrator API Swagger definition can be accessed by adding the /swagger/ui/index#/ suffix to your Orchestrator URL. For example, {baseURL2} /swagger/ui/index#/.

Note: The Swagger authentication expires according to the parameters set in your Orchestrator instance. By default, it is set to 30 minutes. You can change it by modifying the value of the Auth.Cookie.Expire parameter, in the Web.config file.