Enabling API platform for customers

The API platform is a tool that helps Embedded partners securely share content or microservices with their customers. It enables use cases that extend their product's functionality by building recipes triggered by API endpoints.

The following guide covers the concepts and platform API endpoints required to programmatically enable the API platform in customer accounts.

PROCESS OVERVIEW

Enabling the API platform for customers entails the following:

1. Creating API endpoint recipes and collections
2. Creating customer accounts
3. Importing the recipes and collections to customer accounts
4. Creating client/access profiles in customer accounts
5. Starting recipes and activating the endpoints

Creating API endpoint recipes

Best practice

Build and test API endpoint recipes in the Embedded partner's admin account before importing them into customer accounts. Create the recipes in the same folder to simplify the import and export processes.

1

The first step in setting up an API endpoint is to create a recipe that uses the API platform - New API request trigger. Click the Build an API endpoint starting point to automatically select this trigger. Select Build an API endpoint recipe as the recipe starting point

2

Organize these recipes into one or more API Collections. Generally, an API Collection contains endpoints whose access patterns share common features, permitting you to manage them together. For example, if you have a set of Salesforce endpoints used by your sales team in recipes, you might group them together in an API Collection.

3

Activate and test your API endpoints. Reference our API endpoint management and API collection creation guides for detailed information on building and activating endpoints and collections.

4

After creating and testing your endpoints, use the Recipe lifecycle management tool to create a manifest that includes all the collections and endpoints.

---

Creating customer accounts

You can create customer accounts in the UI of the Admin console or by using the Manage customer accounts platform API. The customer ID is returned in the response body when using the API to create customer accounts.

If viewing or creating the customer account in the UI of the Admin console, the customer ID is available in the URL of the customer info page.

Obtain the customer ID in the UI in the URL

Embedded platform API shortcuts

1. Create a customer account: POST /api/managed_users (opens new window)

---

Importing the recipes and collections to customer accounts

You can import recipes and collections to customer accounts in the Workato UI or with Embedded platform APIs.

Before importing recipes from the admin account to the customer account, create a folder in the customer account. The folder must be a top-level folder (nested one level within 'Home').

Use the manifest saved in the admin account to export packages into customer accounts. Exporting copies the endpoints and collections in the package into the customer account.

Embedded platform API shortcuts

1. Create a top-level required folder in the customer account: POST /api/managed_users/:id/folders
2. Export a package from the admin account: POST /api/packages/export/:id
3. Import a package into the customer account: POST /api/managed_users/:id/imports

---

Creating client/access profiles in customer accounts

API clients are groups of users who receive access to one or more API collections through an access profile. For example, members of the same organization comprise an API client and access API collections through individual access profiles. You can create API clients and access profiles in the Workato UI or by using Embedded platform APIs.

1

Add API clients and access profiles to your customer accounts to enable these endpoints. Reference our client and access profile guide for detailed instructions.

2

Assign the collection imported in the preceding step to an access profile. Considering each customer already has an account, you may only need to create one default client and one default access profile.

When you add more collections in the future, update the access profile to include the new collection IDs.

Embedded platform API shortcuts

1. Create an API client: POST /api/managed_users/:id/api_clients
2. Create an access profile within the client: POST /api/managed_users/:id/api_clients/:api_client_id/api_access_profiles
3. Update an access profile: PUT /api/api_access_profiles

---

Starting recipes and activating endpoints

After importing recipes into the customer account, you must start them before activating the endpoints. After the endpoints are activated, you can call the endpoints using the API client.

You can start recipes and activate endpoints in the Workato recipe building UI or by using Embedded platform API endpoints.

If the Embedded partner needs to limit access to endpoints for the API client, the partner may deactivate the endpoints.

Embedded platform API shortcuts

1. Obtain recipe IDs: GET /api/managed_users/:id/recipes
2. Start a recipe: PUT /api/managed_users/:managed_user_id/recipes/:recipe_id/start
3. Activate an endpoint: PUT /api/managed_users/:id/api_endpoints/:api_endpoint_id/enable
4. Disable an endpoint: PUT /api/managed_users/:id/api_endpoints/:api_endpoint_id/enable