These instructions are intended for developers who maintain the integration between UiPath products and external applications.

👍

Requirements

Before you begin:

• The external application must already be registered in Automation Cloud by an organization administrator.
• Obtain the registration details from the organization administrator.

Using the Different Grant Types

After the external application is registered, you must implement the appropriate authorization mechanism for the external application, with the appropriate grant type for the allowed scope, so that the external application can retrieve an access token.

Which authorization grant type to use:

📘

Note:

If a confidential application was granted both user and application scopes, you must implement both grant types.
When the scope name is the same under both user and application scope, as in the case of Orchestrator, the grant type you use determines if the resource is called under user scope or under application scope.

The authorization server for accessing UiPath resources is the UiPath Identity Server, which supports the OAuth 2.0 framework.

Authorization Code

Use this grant type when the registered application is of the type confidential and the request is for user scope.

With this grant type, the flow is as follows:

1. The external application sends an authorize request to the UiPath Identity Server authorize endpoint to get the authorization code.

https://cloud.uipath.com/identity_/connect/authorize?
response_type=code&
client_id={app_id}&
scope={scopes}&
redirect_uri={redirect_url}

• https://cloud.uipath.com/connect/authorize is the Identity Server authorization endpoint.
• response_type=code specifies that the application is requesting an authorization code.
• client_id must contain the Application ID (shown on the External Applications page).
• scope: contains the scopes requested by the application, delimited by a space; for example: OR.Machines OR.Robots.
  Check the endpoint in the API documentation of the resource to get the scope values you need. For example:

• redirect_uri contains the URL where UiPath Identity Server redirects the authorize request after the authorization code is granted.

2. A user must log in to Automation Cloud to authenticate the authorize request.
   The request fails if:

   • the user is not in the organization where the external application was registered
   • for some resources, the logged in user does not have the required permissions for the scope of the request.

3. The external application receives the authorization code.
   Sample authorize request redirect: {redirect_url}?code={authorization_code}&scope={scopes}
   You can use the authorization code only once.

4. The external application requests an access token from UiPath Identity Server using the authorization code and authentication details (client_id and client_secret). These are included in the body of a POST request to the token endpoint https://cloud.uipath.com/identity_/connect/token.
   If you are using Postman or a similar tool, use the content type application/x-www-form-urlencoded.

{
    grant_type: "authorization_code"
    code: "{authorization_code}"
    redirect_uri: "{redirect_url}"
    client_id: "{app_id}"
    client_secret: "{app_secret}"
}

📘

Note:

The client_secret is returned after registering a confidential application in Automation Cloud.
For a non-confidential application, use code_challenge and code_challenge_method instead of the client_secret.

5. The external application receives a response containing the access token, for example:

{
    "access_token":"{access_token}",
    "expires_in":3600,
    "token_type":"Bearer",
    "scope":"{scopes}"
}

Now the application can use the access token to access user resources until the token expires (one hour). See Using the Access Token and Obtaining a Refresh Token for more information.

Authorization Code with PCKE

Use this grant type if the registered application is of the type non-confidential and the request is for user scope.

The flow is the same as when using authorization code, except in the authorize request you need to include the following request query parameters:

• code_challenge_method, which must be S256
• code_challenge, a cryptographically-random string derived from the code_verifier, used to connect the authorization request to the token request.

You must use a code verifier algorithm to generate the code challenge. You can also create your own, as long as it complies with the rfc7636 standard.

https://cloud.uipath.com/identity_/connect/authorize? 
  response_type=code
  &client_id={app_id}
  &scope={scopes}
  &redirect_uri={redirect_url}
  &code_challenge={cryptographically-random string from code_verifier}
  &code_challenge_method=S256

In the POST token request to https://cloud.uipath.com/identity_/connect/token, you need to include code_verifier (the original string used to generate code_challenge) in the request body.
If you are using Postman or a similar tool, use the content type application/x-www-form-urlencoded.

{ 
    grant_type: "authorization_code" 
    code: "{authorization_code}" 
    redirect_uri: "{redirect_url}" 
    client_id: "{app_id}" 
    code_verifier: "{code_verifier}" 
}

The response includes an access token which the application can use to access user resources until the token expires (one hour). See Using the Access Token and Obtaining a Refresh Token for more information.

Client Credentials

For confidential applications to access application scope, the external application requests an access token by sending a POST request that includes the client_id and client_secret to the Identity Server token endpoint: https://cloud.uipath.com/identity_/connect/token.
If you are using Postman or a similar tool, use the content type application/x-www-form-urlencoded.

{
    grant_type: "client_credentials"
    client_id: "{app_id}"
    client_secret: "{app_secret}"
    scope: "{scopes}"
}

Using the Access Token

After the application has an access token, it can use the token to access allowed resources, limited to the selected scopes, until the token expires (one hour).

Here is a sample request to the odata/Machines API that uses an access token in the Authorization header, where the access token contains OR.Machines scope in the scope claim.

curl -X GET "https://cloud.uipath.com/{org_name}/{tenant_name}/orchestrator_/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"l

See the Orchestrator API Swagger at https://cloud.uipath.com/{org_name}/{tenant_name}/orchestrator_/swagger/index.htm for information about the available APIs.

Obtaining a Refresh Token

Access tokens expire in one hour. The external application can get a new access token without user interaction by exchanging a refresh token for it.
Refresh tokens are also valid for only one use and they expire after 60 days.

Both confidential and non-confidential external applications can request a refresh token. To do so, they must include offline_access in the scope parameter of the authorize request so that the authorization code can be used in a token request to get a refresh token.

To get a refresh token, send a POST request with the authorization code to the token endpoint
https://cloud.uipath.com/identity_/connect/token.
If you are using Postman or a similar tool, use the content type application/x-www-form-urlencoded.

The request returns a new access token and a refresh token:

{ 
    "access_token": "{access_token}", 
    "expires_in": 3600, 
    "token_type": "Bearer", 
    "refresh_token": "{refresh_token}", 
    "scope": "OR.Machines OR.Robots offline_access" 
}

To get a new refresh token and a new access token, send a POST request to the token endpoint https://cloud.uipath.com/identity_/connect/token using the refresh_token grant type.
If you are using Postman or a similar tool, use the content type application/x-www-form-urlencoded.

{
    grant_type: "refresh_token"
    client_id: "{app_id}"
    client_secret: "{app_secret}"
    refresh_token: "{existing_refresh_token}"
}

The response returns a new access token and a new refresh token.
The existing refresh token is no longer valid after use, so make sure you use the new refresh token you received.

UiPath Identity Server Endpoints

If you are using Postman or a similar tool, use the content type application/x-www-form-urlencoded for any requests to Identity Server endpoints. If you are making requests programmatically, this is not required.

Discovery:
https://cloud.uipath.com/identity_/.well-known/openid-configuration

Authorization
https://cloud.uipath.com/identity_/connect/authorize

Token:
https://cloud.uipath.com/identity_/connect/token