- Alerts Requests
- Assets Requests
- Calendars Requests
- Environments Requests
- Folders Requests
- Generic Tasks Requests
- Jobs Requests
- Libraries Requests
- License Requests
- Packages Requests
- Permissions Requests
- Personal Workspaces Requests
- Processes Requests
- Process Data Retention Policy Requests
- Queue Items Requests
- Queue Retention Policy Requests
- Robots Requests
- Roles Requests
- Schedules Requests
- Settings Requests
- Storage Bucket Requests
- Tasks Requests
- Task Catalogs Requests
- Task Forms Requests
- Tenants Requests
- Transactions Requests
- Users Requests
- Webhooks Requests
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.
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 |
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:
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 beS256
-
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
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}"
}
{
"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}"
}
{
"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"
curl -X GET "https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/odata/Machines"
-H "Authorization: Bearer {access_token}" -H "accept: application/json"
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
.
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"
}
{
"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.
application/x-www-form-urlencoded
.
{
"grant_type": "refresh_token",
"client_id": "{app_id}",
"client_secret": "{app_secret}",
"refresh_token": "{existing_refresh_token}"
}
{
"grant_type": "refresh_token",
"client_id": "{app_id}",
"client_secret": "{app_secret}",
"refresh_token": "{existing_refresh_token}"
}
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
|