---
source_url: https://itmustbecode.com/dataverse-custom-api-keep-it-private/
title: Dataverse Custom API: Keep It Private
date: 2021-01-25T02:40:22+00:00
categories:
  - blog
tags:
  - custom-api
  - dataverse
  - xrmtoolbox
word_count: 758
reading_time_minutes: 4
type: posts
---

Pursuing my series of blog posts on Dataverse Custom API features, this one will be _'short and sweet'_ and explores the usage of the **IsPrivate** attribute that can be found on the Custom API Table.

_The ability to set an API as a Private message is a unique feature of the Custom API model and does not exist for classic Workflow Custom Actions._

> 🚨The **IsPrivate** Attribute is (currently) **not available/editable** using the out-of-the-box Custom API authoring experience (Model-Driven form). That's a **very good reason** to try my **[Custom API manager](/customapi-manager-for-xrmtoolbox/)** tool for XrmToolBox where the attribute can be set easily. 😏

{{< figure src="./image-52.png" alt="" caption="" >}}

## **Keep It For Yourself**

As per [Microsoft documentation](https://docs.microsoft.com/en-us/powerapps/developer/data-platform/custom-api?WT.mc_id=DX-MVP-5004959), a Custom API with **IsPrivate** set to **true** will be **hidden** (ghosted) from metadata and documentation. Meaning it will **not be discoverable** by metadata queries running against the Dataverse environment.

A good use case for this functionality is for an ISV scenario. For instance, If you develop and ship products/extensions that are installed on your customer's Dataverse environments, you may want to leverage the power of Custom APIs for the **internal operations** of your product.

Now, for obvious **functional** and **IP** reasons, you don't necessarily want to **expose** your Custom APIs signature to other users/developers of the environments where your product is installed. That is where the **IsPrivate** attribute might come useful.

However, It's important to understand that even if a Custom API is **hidden**, anyone who knows the **existence** and the signature (inputs/outputs) of a **private message** will be able to use it like any other (public) Custom APIs. So if you really want to completely **lock** your Custom API from 'nosy' 👃 developers, you will have to implement some kind of **authorization** mechanism. _(out of the scope of this blog post)_

### **Tooling in a Private Message context**

Setting a Custom API as private also has side-effects on any tooling that uses metadata queries. For example, tools like **[crmsvcutil](https://docs.microsoft.com/en-us/dynamics365/customerengagement/on-premises/developer/org-service/create-early-bound-entity-classes-code-generation-tool)** will skip Private Messages when generating 'early bound' classes.

If you really need to generate **early bound** classes for a Private Message, here is a workaround.

### 1- Uncheck the **IsPrivate** attribute temporarily

Using the **Custom API Manager** tool for XrmToolBox, you can set the **IsPrivate** attribute to **False**

{{< figure src="./private.gif" alt="" caption="" >}}

### 2- Generate Early Bound Classes

Generate your early bound classes like you would normally do. I'm using [Daryl Labar](https://twitter.com/ddlabar) [**EarlyBound Generator**](https://www.xrmtoolbox.com/plugins/DLaB.Xrm.EarlyBoundGenerator/) for XrmToolBox in the example below, which is a wrapper around the **crmsvcutil** tool. You can see that when I generate classes for the Actions, my Custom API gets picked-up by the tool.

{{< figure src="./image-64.png" alt="" caption="" >}}

You can then use the generated early bound class of your Custom API in your other plugins assemblies or external programs.

### 3- Put back the IsPrivate flag on the API

Now you can set the **IsPrivate** attrtibute back to **true** and ship your Private Custom API to end-users.

### **Extending Private Messages**

One thing I noticed while playing around with the feature is that even if you set your API to be extendable by 3rd parties ( **AllowCustomProcessingStep = SyncAndAsync**) ( _see my previous [blog post](/dataverse-custom-api-allowcustomprocessing-explained/) on that matter_) and your API is marked as **Private**, you will not be able to attach a plugin step on the message using the plugin registration tool.

This makes sense since the **plugin registration tool** needs to make a **metadata** query to show available messages where you can attach a plugin step.

{{< figure src="./image-63.png" alt="" caption="" >}}

## **Summary**

There is not much more to say, the name of the **IsPrivate** attribute **speaks by itself**. It gives Dataverse developers a way to hide Custom API messages by making them impossible to discover. It's a feature that is **unique** to the Custom API model and it can have a real **business value** in certain scenarios.

Happy **API**'ing!

## **Links**
{{< linkcard url="/customapi-manager-for-xrmtoolbox/" title="Dataverse Custom API Manager · XrmToolBox" summary="Manage Dataverse Custom APIs and their request parameters and response properties with XrmToolBox." image="./2021-01-03_19-53-32.png" domain="itmustbecode.com" new_tab="false" nofollow="false" >}}

{{< linkcard url="https://www.xrmtoolbox.com/plugins/DLaB.Xrm.EarlyBoundGenerator/" title="Early Bound Generator · XrmToolBox" summary="Generates Early Bound Entities/Option Sets/Actions. Uses CrmSvcUtil from the SDK, and shows command line used to create the classes." image="/linkcards/7963c972123cfedd.png" domain="www.xrmtoolbox.com" new_tab="true" nofollow="true" >}}

{{< linkcard url="/dataverse-custom-api-allowcustomprocessing-explained/" title="Dataverse Custom API: AllowCustomProcessing Explained" summary="This article explains the AllowedCustomProcessingStep attribute and the differences between Dataverse Custom APIs and traditional Workflow Custom Actions." image="./messagehack-2.png" domain="itmustbecode.com" new_tab="false" nofollow="false" >}}


{{< linkcard url="https://learn.microsoft.com/en-us/power-apps/developer/data-platform/custom-api?WT.mc_id=DX-MVP-5004959" title="Create and use Custom APIs (Microsoft Dataverse) - Power Apps" summary="Custom API is a new code-first way to define custom messages for the Microsoft Dataverse" image="/linkcards/f69ad1e3eed32c06.png" domain="learn.microsoft.com" new_tab="true" nofollow="true" >}}


{{< linkcard url="https://docs.microsoft.com/en-us/dynamics365/customerengagement/on-premises/developer/org-service/create-early-bound-entity-classes-code-generation-tool?WT.mc_id=DX-MVP-5004959" title="Create early bound entity classes with the code generation tool (CrmSvcUtil.exe) (Developer Guide for Dynamics 365 Customer Engagement)" summary="Learn how to create early bound entity classes with the code generation tool, CrmSvcUtil.exe, for Dynamics 365 Customer Engagement (on-premises)." image="/linkcards/f69ad1e3eed32c06.png" domain="docs.microsoft.com" new_tab="true" nofollow="true" >}}

Post Image by [PublicDomainPictures](https://pixabay.com/users/publicdomainpictures-14/?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=71232) from [Pixabay](https://pixabay.com/?utm_source=link-attribution&utm_medium=referral&utm_campaign=image&utm_content=71232)