API Access

Overview

Data Service Open API allows you to manage UiPath^® Data Service resources from an external application of your choice, and does so by enabling you to authorize the external app without sharing any credentials, through the Oauth 2.0 authorization framework.

API Permissions

To use the Data Service OpenAPI, you must grant API permissions to the external application. These API permissions are known as scopes, and there are three types for Data Service:

• DataService.Schema.Read - this User Scope allows your external app to read your tenant's Data Service schema, and it's dependent on the user's permissions.
• DataService.Data.Read - this User Scope allows your external app to read your tenant's Data Service data, and it's dependent on the user's permissions.
• DataService.Data.Write - this User Scope allows your external app to edit your tenant's Data Service data by deleting, updating or creating new data, and it's dependent on the user's permissions.

Learn more about the user roles and permissions in Data Service.

Download the OpenAPI Specification

Once you set the permissions for your external application and users, download the OpenAPI specification of your tenant Data Service data:

• On the Data Service page, click API Access, then select Download OpenAPI file (JSON).

This operation downloads the OpenAPI 3.0 specifications of your tenant Data Service entities, in JSON format.

Clicking Copy OpenAPI link copies the API endpoint that generates the tenant Data Service OpenAPI specification.

Authorizing the API Calls

To access the user-scoped resources of Data Service, authorize your external application with one of the following methods:

• Authorization Code (for confidential external apps)

• Authorization Code with PCKE (for non-confidential external apps)

API Endpoints

OAuth2.0 authorization framework helps you generate a access token that allows your external application to make REST API calls to Data Service endpoints, for a limited time (one hour).

A Data Service API endpoint has the following syntax:

• HTTP method + BaseURL + The resource category + The Data Service entity + The Operation + Path variables and query parameters

  
  

  

  
  

  Data Service Entity Example

  To describe each API request/response body, we are using the Olympics entity fields created in the Data Service. While we document the generic endpoint, such as Get Entity Records, your endpoint contains the exact name of your entity (for example, Get Olympics Records). The response and request bodies include all the fields from your entity, replicating the entity's structure.
  
  

  

  
  

  Further, let's use the Data Service API guide to dive into each endpoint and discover how you can put it to good use.

Accessing Data Service resources using external applications

Configuring fine-grained access for external apps

External apps use their own client credentials to access Data Service resources instead of impersonating a user.

When an external application wants to perform an action within an entity, Data Service checks whether the app has the required permissions to access the corresponding resources. As no user in involved in the authentication, requesting any resource generates an access token that verifies the assignments your app has at the tenant and entity levels. Only after a successful validation, the external application gains access the resources for which it has been granted permissions.

Creating external apps

As an admin, follow these steps to create an external app and configure it to access Data Service resources:

1. In your organization, navigate to Admin > External Applications. The External Applications page is displayed.

2. Click Add Application:

   1. Provide a name for your external app.

   2. Select the type for your external app.

   3. Click Add. Your external app is displayed in the External applications list.

Say something about dataService.default scope For confidential applications that have been assigned custom Data Service roles, you need to request the DataService.Default scope. This scope uses an access token to check the assignments your app has at the tenant and entity levels. Only after a successful validation, the external application can access the resources to which it has been granted access.

Adding external apps to a tenant

As a Data Service administrator, follow these steps to grant an external app access to all entities in the selected tenant:

1. In your Data Service instance, navigate to the Manage Access page.

   

2. On the Manage Access page, click the Assign Roles button.

3. In the Assign Roles panel:

   1. In the Add names field, type the name of your external app, then select it from the list.

   2. From the Select Roles list, select the custom role previously created and the Data reader role. You can select other roles you want to assign to your external app, but Data Reader is a mandatory selection.

   3. Click Save. Your external app is displayed in the list from the Assign Roles tab.

      

Adding external apps to an entity

As a Data Service admin, follow these steps to manage the access of an external app to specific entities:

1. In your Data Service instance, navigate to the Manage Access page.

   

2. On the Manage Access page, click the Create Role button.

3. In the Create Role panel:

   1. Provide a name for the custom role.

   2. Assign the desired administrative permissions.

   3. Under the Data Access Permissions section, click Add Entity, select the desired entity, then select the permissions the external app can have within that entity.

   4. Click Save. The custom role for your external app is displayed in the list from the Roles tab.