- Getting Started
- The Swagger Definition
- Examples using the Orchestrator API
- 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
- Queue Items Requests
- Robots Requests
- Roles Requests
- Schedules Requests
- Settings Requests
- Tasks Requests
- Task Catalogs Requests
- Task Forms Requests
- Tenants Requests
- Transactions Requests
- Users Requests
- Webhooks Requests
- Platform Management APIs
Accessing UiPath Resources Using External Applications
These instructions are intended for developers who maintain the integration between UiPath products and external applications in an environment with an on-premises Orchestrator installation or a self-hosted Orchestrator installation.
Before you begin:
- The external application must already be registered in External Applications by the organization administrator.
- Obtain the registration details from the organization administrator.
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 (instructions) |
confidential |
application |
Client credentials (instructions) |
non-confidential |
user |
Authorization code with PKCE (instructions) |
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.
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). See Using the Access Token and Obtaining a Refresh Token for more information.
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.
{BaseURL}/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
{BaseURL}/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
{BaseURL}/identity/connect/token
, you need to include
code_verifier
(the original string used to generate
code_challenge
) in the request body.
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_id
and client_secret
to the Identity Server
token endpoint: {BaseURL}/identity/connect/token
.
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}"
}
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 "{OrchestratorURL}/odata/Machines"
-H "Authorization: Bearer {access_token}" -H "accept: application/json"l
curl -X GET "{OrchestratorURL}/odata/Machines"
-H "Authorization: Bearer {access_token}" -H "accept: application/json"l
{OrchestratorURL}/swagger/index.html
for information about the available APIs.
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.
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
{BaseURL}/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"
}
{BaseURL}/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}"
}
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.
application/x-www-form-urlencoded
for any requests to Identity Server endpoints. If you are making requests programmatically, this is not required.
{BaseURL}/identity/.well-known/openid-configuration
{BaseURL}/identity/connect/authorize
{BaseURL}/identity/connect/token