External Applications (OAuth)

These instructions are intended for developers who maintain the integration between UiPath products and external applications using the UiPath functionality based on the OAuth framework.

Tip:

Before you begin:

• The external application must already be registered 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:

Application Type	Scope	Required Grant Type
confidential	user	Authorization code
confidential	application	Client credentials
non-confidential	user	Authorization code with PKCE

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.

Fine-grained Access

For confidential applications with fine-grained access configured via Orchestrator, you need to request the OR.Default scope, which allows the application to check for assignments made in Orchestrator, at the tenant and folder levels. The application can then access the resources it's been granted access to in those tenants and folders.

For example, you want an external application to view jobs and machines across all tenants in the organization. By leveraging the fine-grained access functionality, you can also configure the application to view queues in one folder.

To get the access token for your external app in this scenario, you should request the following scopes: OR.Jobs.Read, OR.Machines.Read, OR.Default. This grants your app View permissions on Jobs and Machines across all tenants in the organization, and also View on Queues in the folder, provided that the external app has been assigned to it and granted the required permissions via a role.

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&
   acr_values={value}&
   client_id={app_id}&
   scope={scopes}&
   redirect_uri={redirect_url}

   Option	Description
   https://cloud.uipath.com/identity_/connect/authorize	The Identity Server authorization endpoint.
   response_type=code	Specifies that the application is requesting an authorization code.
   acr_values	Allows Identity Server to apply an authentication policy based on the organization to which the user belongs. Can take different values: acr_values=tenant:{target organization GlobalId} - the organization ID serves as an ACR value. acr_values=tenantName:{target organization name} - the organization name acts as an ACR value.
   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. Note: 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 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.

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

   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 External Applications.

   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).

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/{organizationName}/{tenantName}/orchestrator_/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"

Note: See the Orchestrator API Swagger at https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/swagger/index.html 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. Both confidential and non-confidential external applications can request a refresh token.

Refresh tokens are also valid for only one use and they expire after 60 days.

To request a refresh token, you 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.

Getting a Refresh Token

Send a POST request with the authorization code to the token endpoint

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

Note: 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" 
}

Getting 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.

Note: 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}"
}

Note: If the external application is non-confidential and utilizing the authorization code with the PKCE grant type, remove the client_secret parameter from the request body.

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.

Identity Server layer	Endpoint	Description
Discovery	https://cloud.uipath.com/identity_/.well-known/openid-configuration	Use this endpoint to retrieve metadata about your Identity Server instance.
Authorization	https://cloud.uipath.com/identity_/connect/authorize	Use this endpoint to request tokens or authorization codes via the browser. This process includes authentication of the end-user and optionally consent.
Token	https://cloud.uipath.com/identity_/connect/token	Use this endpoint to programmatically request tokens. Note that for this endpoint, the content type must be application/x-www-form-urlencoded.