#App Registration

Before using the APIs, you must register an app and grant permissions to the app. With the registered app, you can use the generated application (client) ID for authentication.

#Register an App

Complete the following steps to register an app:

1. Go to the Settings page and select API app registration in the Additional area.

2. On the API app registration page, click Create app registration under the Public API tab.

3. In the Basic information step, complete the following information:

   1. Enter a name for the app.

   2. Select the corresponding permissions that you need to grant to this app.

4. Click Next.

5. In the Customer scope step, select All customers, Specific customers, or Customer groups as the scope.

6. Click Next.

7. In the Certificates and secrets step, follow the instructions below to configure credentials:

   Credentials enable applications to identify themselves to the authentication service when receiving tokens at a web addressable location (using an HTTPS scheme). For a higher level of assurance, we recommend using a certificate (instead of a client secret) as a credential.

   • Select the Certificate tab, and then click Upload certificate to upload a certificate (.cer file). The certificate serves as credentials that allow your application to authenticate itself, requiring no interaction from a user at runtime. You can refer to Prepare a Certificate to prepare a certificate.

   • Select the Client secret tab, click Add client secret, set the Effective duration to 1 year, 2 years, or 3 years, and then click Add to generate a client secret. Client secret values cannot be entirely shown once they are saved. To get a client secret value for later use, click the Copy () button to copy and save it upon creation.

     If you want to delete a certificate or client secret, click the Delete () button.

8. Click Save to save your configurations.

   When you finish the registration, click the app name and you can copy the generated application (client) ID on the app details page.

#Edit an App

Complete the following steps to edit an app:

1. On the API app registration page, click the app name to access the app details page.

2. In the Basics tab, you can update the app name, permissions, and customer scope if required.

3. In the Certificates and secrets tab, you can view and manage the certificate and client secret.

#Delete Apps

On the API app registration page, select the apps and click Delete. The selected apps will be deleted.

#Prepare a Certificate

This section details how to prepare certificate files.

To prepare self-signed certificate files based on your scenario, choose one of the following methods.

#Use a Key Vault in Azure to Prepare Certificates

Before preparing a certificate with this method, make sure you have a key vault in Azure. If you have an Azure subscription but do not have any key vaults, refer to the instructions in Create akey Vault in Azure below. Then, refer to the steps below to prepare the certificate.

1. In the , navigate to Key vaults.

2. On the Key vaults page, select a key vault and then select Certificates in the left menu.

   

3. In the Certificates panel, click Generate/Import and complete the required fields. The screenshot below is a sample certificate.

   *Note: In the Content Type field, select PKCS #12.

   

4. Click Create and wait for the Status of the certificate to become Enabled. You can click Refresh to update the status if needed.

   

5. Click the name of the certificate, and then select the current version of the certificate.

6. Click Download in CER format and Download in PFX/PEM format to download the certificate files to your local machine.

   

7. When you have the certificate (.pfx file), you must set a password to protect the certificate.

   1. Open Windows PowerShell and paste the following script to Windows PowerShell. Replace [Full path to your PFX] with the full path of the certificate (.pfx file) in your local machine. Note that quotes are required when you enter the commands.

      $pfxPath=”[Full path to your PFX]” Export-PfxCertificate -Password $(Read-Host -AsSecureString -Prompt "Enter a password to protect the certificate") -PFXData $(Get-PfxData -FilePath $pfxPath) -FilePath $pfxPath

   2. Press Enter to execute the script.

   *Note: The .pfx file contains your private key.

Create a Key Vault in Azure

Make sure you have an Azure subscription that contains Azure Key Vault. Then follow the instructions below:

1. Create an application. This application is only used for Azure Key Vault.

   1. In the (or ), navigate to Identity > Applications > App registrations (or Microsoft Entra ID > App registrations).

   2. Click New registration.

   3. On the Register an application page, configure the application settings.

   4. Click Register to create your application.

   5. After the application is created successfully, copy the application ID.

2. Add a client secret for the application.

   1. After creating the application, click Certificates & secrets in the left menu.

   2. In the Client secrets field, click New client secret.

   3. In the Add a client secret pane, enter a description for the client secret and select a duration.

   4. Click Add. The value of the client secret is automatically generated and displayed.

   5. Copy the client secret value. You will need to provide the value when configuring the encryption profile.

      *Note: The value will be hidden after you leave or refresh the page.

3. Create a key vault.

   1. In the Microsoft Azure portal, enter Key vaults in the search box on the top, and then select the first result to access the Key vaults page.

   2. Click Create. The Create a key vault page appears.

   3. In the Basics tab, provide the basic information for the key vault, and then click the Access configuration tab.

   4. In the Access policies section, click Create.

   5. The Create an access policy pane appears. In the Permissions tab, select the following Key permissions:

      • In the Key Management Operations field, select Get.

      • In the Cryptographic Operations field, select Decrypt and Encrypt.

   6. Click Next to go to the Principal tab.

      1. In the Principal pane, complete the following steps:

      2. Enter the application name or application ID in the search box.

      3. Select the application and click Select at the bottom.

      4. Click Next at the bottom.

   7. Click Create to add the access policy.

   8. Click the Networking tab.

   9. Select Enable public access which allows all networks to connect to this key vault.

   10. Click the Tags tab and you can add tags to categorize your key vault.

   11. Click Review + create to review all of your configurations first, and then click Create at the bottom to create the key vault.

       *Note: If you need to change some settings before creating the key vault, you can click the < Previous button to change previous settings.

4. Create a key.

   1. On the Key vaults page, click the newly created key vault.

   2. Click Keys in Settings. In the Keys pane, click Generate/Import and create a key.

   3. In the Keys pane, click the key name, and then click the current version. The key properties are displayed.

   4. Copy the key identifier. You will need to provide the key identifier when configuring the encryption profile.

#Use Windows PowerShell to Prepare Certificates

To create a self-signed certificate using Windows PowerShell, refer to the following steps:

*Note: The steps below are based on running Windows PowerShell on a machine with the Windows 10 or Windows 11 operating system.

1. Right-click Windows PowerShell on the machine and select Run as administrator from the drop-down list.

2. Refer to the following example to use the New-SelfSignedCertificate cmdlet to generate certificate files.

   $cert = New-SelfSignedCertificate -Subject CN=AvePointCustomApp -CertStoreLocation 'Cert:\CurrentUser\My' -NotAfter (Get-Date).AddMonths(60)

   Press Enter on the keyboard.

3. Export the .crt (or .cer) file by entering the following command:

   Export-Certificate -Cert $cert -FilePath AvePointCustomApp.crt

   Note the following:

   • If you want to export a .cer file, replace the .crt with .cer in the cmdlet example above.

   • In this command, the file will be saved to the current working directory of the PowerShell session. If you want to specify a different directory, provide the full path by referring to the cmdlet example below:

     Export-Certificate -Cert $cert -FilePath "C:\Temp\AvePointCustomApp.crt"

4. Export the .pfx file with a password by entering the following command:

   Export-PfxCertificate -Password $(Read-Host -AsSecureString -Prompt "Enter a password to protect the certificate") -Cert $cert -FilePath AvePointCustomApp.pfx

   Note the following:

   • The .pfx file contains your private key.

   • In this command, the file will be saved to the current working directory of the PowerShell session. If you want to specify a different directory, provide the full path by referring to the cmdlet example below:

     Export-PfxCertificate -Password $(Read-Host -AsSecureString -Prompt "Enter a password to protect the certificate") -Cert $cert -FilePath "C:\Temp\AvePointCustomApp.pfx"

   Press Enter on the keyboard.

If you want to remove the certificate files, enter the following command and press Enter on the keyboard:

Remove-Item "Cert:\CurrentUser\My$($cert.Thumbprint)”