Steps for authenticating and using Orchestrator cloud API

Hi All,

As I see lot of topics being posted on the authentication of Orchestrator cloud API, I decided to provide the step by step process of authentication and using the API.

Here are the steps:

  1. Here is the documentation: About OData and References

  2. Generating Code Challenge and Code Verifier :

    a) This is the URL you need to run in any browser https://repl.it/languages/nodejs. and it will open the page like this

    This is a nodeJS server which will retrieve us the specific code verifier based on our machine ID

    b) Copy the below code and paste it in the index.js text area and run the code

    function base64URLEncode(str) {
     return str.toString('base64')
     .replace(/\+/g, '-')
     .replace(/\//g, '_')
     .replace(/=/g, '');
     }
    function sha256(buffer) {
     return crypto.createHash('sha256').update(buffer).digest();
    }
    
    console.log("Generating challenge and Verifier");
    var cryptoResult = crypto.randomBytes(32);
    var verifier = base64URLEncode(cryptoResult);
    var challenge = base64URLEncode(sha256(verifier));
    console.log("Code challenge: " + challenge)
    console.log("Code verifier: " + verifier);
    

    That will give you the code verifier and code challenger. Make sure you copied them in a seperate text file as we are going to use those two in the next steps

  3. Getting Authorization Code:

    a) This is the URL where we need to replace the CODE Challenge we got from the above step

     https://account.uipath.com/authorize?response_type=code&nonce=b0f368cbc59c6b99ccc8e9b66a30b4a6&state=47441df4d0f0a89da08d43b6dfdc4be2&code_challenge=**[Code Challenge]**&code_challenge_method=S256&scope=openid+profile+offline_access+email 
    &audience=https%3A%2F%2Forchestrator.cloud.uipath.com&client_id=5v7PmPJL6FOGu6RB8I1Y4adLBhIwovQN&redirect_uri=https%3A%2F%2Faccount.uipath.com%2Fmobile
    

    b) After replacing the code challenge in the URL, open a browser and paste the above URL and run. It will redirect to the Orchestrator login page. Please enter the credentials of your orchestrator and then login which will return you the Authorization Code and a simple text as OK in the browser page

    c) Copy the entire URL which contains the code and state. Copy the text from code to next query parameter (&) and make sure you have pasted it somewhere as we need to use it in next steps

  4. Getting Refresh Token:

    a) Open POSTMAN or UiPath HTTP request and use the below URL and send a post request to get the Access Token and ID token

      URL : https://account.uipath.com/oauth/token
       Header : Content-Type: application/json
       Body : {
                 "grant_type": "authorization_code",
                "code": "[Authorization code]",
                "redirect_uri": "https://account.uipath.com/mobile",
                "code_verifier": "[Code verifier]",
               "client_id": "5v7PmPJL6FOGu6RB8I1Y4adLBhIwovQN"
                 }
    

    Make sure you have replaced the authorization code and code verifier in the above body which will give you the access tokens and id tokens as in the screenshot. copy all those to the new file as we are going to use them in next steps

  5. Getting Account Logical Name:

    a) This is nothing but the tenant name, but perform this action to get the Account Logical Name as we are using it in future requests :slight_smile:

       Request Type : **GET**
       URL : https://platform.uipath.com/cloudrpa/api/getAccountsForUser
    

    Here, no need to pass the headers and body , but in the authorization, select OAuth2(Uipath) or Bearer token (Postman)

    This will give you the tenant name and the account logical name. Save those two as well :slight_smile:

  6. Getting Service Instance Logical Name:

    This one is to get the robots and service logical name. This is the last step in the process :smiley:

    Make sure you have replaced the account logical name in the URL

    URL : UiPath
    Same as above process, just send the bearer token (ID TOKEN we got above as OAuth2 token), you will get the results


yes, now we have all the required info and the required tokens and all,

Now as we have to authenticate with the URL in the previous versions of API, we need to send the final request for the URL

 URL : https://platform.uipath.com/api/account/authenticate
 Authorization code : ID token we got above
Header : Content-Type: application/json
Body : {
            "tenancyName" : "Documentation",
            "usernameOrEmailAddress" : "Documentation",
            "password" : "DocumentationAPItest"
            }

which will give us the access token which we can use for all the remaining requests like start job etc.,

Copy the result and use that result value in all the remaining requests :smiley:


Once the token is expired, it is hard to do all the above steps, so we can simply use refresh token to get the access token and ID token as above :smiley:

for that

  Request type : post
  URL : https://account.uipath.com/oauth/token
  Header : content-type application/json
  Body : {
            "grant_type": "refresh_token",
            "client_id": "5v7PmPJL6FOGu6RB8I1Y4adLBhIwovQN",
           "refresh_token": "[refresh token]"
             }

Here is the result :

That’s all, you can start using the API for jobs starting or whatever you want :smiley:

Hope this helps someone in the forum

23 Likes

Hey @HareeshMR

It’s a great post bro!!!

Great work!!!

I’ll give a like it few hours as my daily like quota is over :rofl::rofl::rofl:

7 Likes

Hey @HareeshMR

Cool post! It is very informative and easy-to-understand instructions.
I know that even beginners/rookies can easily do this because it is very informative.

Keep it up! :slight_smile:

9 Likes

Thank you @Lahiru.Fernando and @Jan_Brian_Despi

Actually, to avoid the same topic about the authentication of Orchestrator API, I thought of doing this. Hope this will help people who are trying to use Orchestrator through API

3 Likes

@HareeshMR
sorry for late reply
Great job bro. Actually This post Helpful for me also because I am also spending less time in Orchestrator API. Thanks

3 Likes

Thank you bro @sandeep13 :slight_smile:

2 Likes

@HareeshMR,
1.In step 6 which token we have to use “Id token” or “Access token” for authorization?
2.What is the tenancyName?
3. the username and the password are the login credentials which we use to login into platform.uipath.com?

Thanks
Vashisht.

We need to use ID TOKEN @Vashisht

We can get it in the services tab of the UiPath orchestrator page or the Account logical name we get from the request

Yes

1 Like

I tried this but getting stuck at postman step 4 while getting refresh token though I have replaced with Authorisation token and code .
Getting Invalid autorisation code. Not understanding

Authorization code also expires in a certain period of time @samrudh

Can you please try generating new authorization code again?

1 Like

Bro done with all the steps. It was very helpful. But last step to authenticate is not happeining getting bad request.

I m passing Autorisation Bearer token : token id . Is it correct?
Please help me with this last step.

Yes, you need to pass ID token. bad request in the sense, it seems you are missing the parameter to be sent to the server. can you check all the required? I mean the headers, body etc.,

and make sure that is a post request. Make sure the tenant name is also correct

Can you confirm, the ID token is generated in the last 30 minutes or before?

1 Like

Not sure about time. So if it exceeds more than 30 mins. From what step should I follow from ?

Not sure if it is only for 30 mins or 1 hour @samrudh. That’s not at all a problem now as per the error you posted, make sure all the inputs are correct

1 Like

I passed tenancy name:
username
password

and I have passed Authorization bearer token : [token id]

What else needs to be sent?

Can you try adding the header as

content -type : application/json

1 Like

added still not working Bad request

Can you check the credentials once ? This is purely related to the credentials and tenent name @samrudh

1 Like

Just wanted to confirm @HareeshMR . Is tenancyName same as “serviceInstanceName”: ?
and username is “accountName”: ? and password is the password of account?

To avoid confusion,

  1. Tenant name is accountLogicalName or when you open the orchestrator and click on services tab, you will see the tenant name on the right side pane
  2. username is the one you used to login to the orchestrator , may be it is a mail ID
  3. Password is also the same which you used to login to the orchestrator @samrudh
1 Like