English

Home > AvePoint Cloud Governance API

AvePoint Cloud Governance API

AvePoint Cloud Governance provides APIs. Refer to the instructions below to use the APIs. You can also refer to the coding details demonstrated in cloud-governance-client.

C#

AvePoint Cloud Governance provides a Software Development Kit (SDK) for the C# language. Refer to the instructions below to get started:

Install the AvePoint Cloud Governance Client by using the following:
```
Install-Package Cloud.Governance.Client
```

Choose any of the following methods to authenticate with AvePoint Cloud Governance API:

Authentication via a client ID and client secret

Navigate to System settings > API authentication profiles and click Create on the ribbon.
Enter a name for the profile.
Configure a duration for the client secret. The start time is the profile created time. Enter a number in the text box and select Days, Weeks, Months, or Years as the unit of time.
Define the services that can be called using this AvePoint Cloud Governance API access token.
Click Save to save your configurations.
The Note window appears displaying the API authentication details. Click the Copy button to copy the client secret to your clipboard.

NOTE
The client secret will only be displayed one time, and you cannot retrieve it after you close the window.

Refer to the example below to authenticate with AvePoint Cloud Governance API.

The value of the userPrincipalName parameter is the login name of a delegated user that will be used to invoke the AvePoint Cloud Governance API. Make sure the user’s account has been added to AvePoint Online Services and has the subscription for AvePoint Cloud Governance.

The API URLs vary with AvePoint Cloud Governance environments. Choose one of the following API URLs according to the environment you are using.

AvePoint Cloud Governance Environment	API URL
The production environment for commercial use	https://go-api.avepointonlineservices.com
The production environment for U.S. Government Public Sector	https://governance-api-us-gov.avepointonlineservices.com
The Insider environment – the East US (Virginia) data center	https://insider-governance-api-us-east.avepointonlineservices.com
The Insider environment – the North Europe (Ireland) data center	https://insider-governance-api-north-europe.avepointonlineservices.com

Authentication via an app registered in AvePoint Online Services

NOTE

This method cannot limit the services that can be called using the Cloud Governance API access token.

Go to the AvePoint Online Services > Administration > App registration page to register an app for AvePoint Cloud Governance. For details, refer to Configure App Registrations.

After you registered the app, get the access token to authenticate with AvePoint Cloud Governance Public API. To get the access token, specify the following attributes:

Element	Description
identityServiceUrl	For Commercial environment, use: https://identity.avepointonlineservices.com; For U.S. Government environment, use: https://identity-gov.avepointonlineservices.com
clientId	Specifies the application (client) ID of the app you registered through AvePoint Online Services > Administration > App registration.
clientsecret	Specifies the client secret of the app you registered through AvePoint Online Services > Administration > App registration.
scope	Specifies the permission that has been granted to the app. For AvePoint Cloud Governance, the value is cloudgovernance.fullcontrol.all.
thumbprint	The thumbprint of the corresponding .pfx certificate file of the .cer certificate you used when registering the app.
TokenLifetimeInMinutes	Specifies an expiration time for the retrieved token. The unit of time is Minute.
username	Specifies a username as a delegated user to call Cloud Governance API.

Example:

Certificate as a credential:

private static void GetTokenByClientCertificate()
{
     var client = new HttpClient();
 	var disco = client.GetDiscoveryDocumentAsync("{identityServiceUrl}").GetAwaiter().GetResult(); ;
 	if (disco.IsError)
 	{
 		 Console.WriteLine(disco.Error);
 		 return;    
 	}
 	
 	var tokenResponse = client.RequestClientCredentialsTokenAsync(new ClientCredentialsTokenRequest
 										    
 	{
 		Address = disco.TokenEndpoint,        
 		ClientAssertion = new ClientAssertion()
 	    {
 		    Type = OidcConstants.ClientAssertionTypes.JwtBearer,            
 			Value = CreateClientAuthJwt(disco)        
 		},
 	   Scope = "cloudgovernance.fullcontrol.all",
 	}).GetAwaiter().GetResult();
 	if (tokenResponse.IsError)
 	{
         Console.WriteLine(tokenResponse.Error);
 		return;    
 	}
 	Console.WriteLine(tokenResponse.Json);
}
private static string CreateClientAuthJwt(DiscoveryDocumentResponse response)
{
  var clientId = "{client ID}";
  // set exp to 5 minutes
  var tokenHandler = new JwtSecurityTokenHandler { TokenLifetimeInMinutes = 5 };
  var securityToken = tokenHandler.CreateJwtSecurityToken(
      // iss must be the client_id of our application
      issuer: clientId,
      // aud must be the identity provider (token endpoint)
      audience: response.TokenEndpoint,
      // sub must be the client_id of our application
      subject: new ClaimsIdentity(
        new List<Claim> { new Claim("sub", clientId),
        new Claim("username", "{username}"),
        new Claim("jti", Guid.NewGuid().ToString())}),
      // sign with the private key (using RS256 for IdentityServer)
      signingCredentials: new SigningCredentials(
        new X509SecurityKey(new X509Certificate2(LoadCertificate())), "RS256")
  );
  return tokenHandler.WriteToken(securityToken);
}
private static X509Certificate2 LoadCertificate()
{
  //Gao certificate
  var store = new X509Store(StoreName.My, StoreLocation.LocalMachine);
  store.Open(OpenFlags.ReadOnly);
  var certificate = store.Certificates.Find(
          X509FindType.FindByThumbprint,
          "{thumbprint}",
          false)[0];
  return certificate;
}

Client secret as a credential:

private static void GetTokenByClientSecret()
{
    var client = new HttpClient();
    var disco = client.GetDiscoveryDocumentAsync("https://identity.avepointonlineservices.com").GetAwaiter().GetResult();
    if (disco.IsError)
    {
        Console.WriteLine(disco.Error);
        return;
    }
    var tokenResponse = client.RequestClientCredentialsTokenAsync(new ClientCredentialsTokenRequest
    {
        Address = disco.TokenEndpoint,
        ClientId = "{client id}",
        ClientSecret = "{clientsecret}",
        Scope = "cloudgovernance.fullcontrol.all",
        Parameters = new Parameters() { new KeyValuePair<string, string>("username", "{user name}") }
    }).GetAwaiter().GetResult();
    if (tokenResponse.IsError)
    {
        Console.WriteLine(tokenResponse.Error);
        return;
    }
    Console.WriteLine(tokenResponse.Json);
}

You can find more information on what is possible with AvePoint Cloud Governance API here, as well as the coding details and examples.

PowerShell

AvePoint Cloud Governance provides a Software Development Kit (SDK) for integration with PowerShell. Refer to the instructions below to get started:

Use the following command to install the Cloud Governance PowerShell module:
```
Install-Module -Name Cloud.Governance.Client
```
NOTE
The Cloud Governance PowerShell module requires PowerShell 3.0 or above.

Choose any of the following methods to authenticate with AvePoint Cloud Governance API:

Authentication via a client ID and client secret

Navigate to System settings >API authentication profiles and click Create on the ribbon.
Enter a name for the profile.
Configure a duration for the client secret. The start time is the profile created time. Enter a number in the text box and select Days, Weeks, Months, or Years as the unit of time.
Define the services that can be called using this AvePoint Cloud Governance API access token.
Click Save to save your configurations.
The Note window appears displaying the API authentication details. Click the Copy button to copy the client secret to your clipboard.

NOTE
The client secret will only be displayed one time, and you cannot retrieve it after you close the window.

Refer to the example below to authenticate with AvePoint Cloud Governance API.

The API URLs vary with AvePoint Cloud Governance environments. Choose one of the following API URLs according to the environment you are using.

AvePoint Cloud Governance Environment	API URL
The production environment for commercial use	https://go-api.avepointonlineservices.com
The production environment for U.S. Government Public Sector	https://governance-api-us-gov.avepointonlineservices.com
The Insider environment – the East US (Virginia) data center	https://insider-governance-api-us-east.avepointonlineservices.com
The Insider environment – the North Europe (Ireland) data center	https://insider-governance-api-north-europe.avepointonlineservices.com

Authentication via an app registered in AvePoint Online Services

NOTE

This method cannot limit the services that can be called using the Cloud Governance API access token.

Go to the AvePoint Online Services > Administration > App registration page to register an app for AvePoint Cloud Governance. For details, refer to Configure App Registrations.

After you registered the app, get the access token to authenticate with AvePoint Cloud Governance Public API. To get the access token, specify the following attributes:

Element	Description
identityServiceUrl	For Commercial environment, use: https://identity.avepointonlineservices.com; For U.S. Government environment, use: https://identity-gov.avepointonlineservices.com
clientId	Specifies the application (client) ID of the app you registered through AvePoint Online Services > Administration > App registration.
clientsecret	Specifies the client secret of the app you registered through AvePoint Online Services > Administration > App registration.
scope	Specifies the permission that has been granted to the app. For AvePoint Cloud Governance, the value is cloudgovernance.fullcontrol.all.
certificate	The path of the corresponding .pfx certificate file of the .cer certificate you used when registering the app.
username	Specifies a username as a delegated user to call Cloud Governance API.

Example

Certificate as a credential:

function Get-IdentityServiceToken {
  [CmdletBinding()]
  [OutputType([string])]
  Param(
      [Parameter(Mandatory)]
      [string]$IdentityServiceUri,
      [Parameter(Mandatory)]
      [string]$Scope,
      [Parameter(Mandatory)]
      [string]$ClientId,
      [Parameter(Mandatory)]
      [Alias("Certificate", "Cert")]
      [System.Security.Cryptography.X509Certificates.X509Certificate2]$SigningCertificate
  )
  PROCESS {
      'Calling method: Get-IdentityServiceToken' | Write-Debug
      $encodedThumbprint = ConvertTo-Base64UrlEncodedString -Bytes $SigningCertificate.GetCertHash()
      $headerTable = [ordered]@{typ = "JWT"; alg = "RS256"; kid = $encodedThumbprint }
      $header = $headerTable | ConvertTo-Json -Compress | ConvertTo-Base64UrlEncodedString
      $now = Get-Date
      $currentEpochTime = Convert-DateTimeToEpoch -DateTime $now
      $notBefore = $currentEpochTime
      $futureEpochTime = Convert-DateTimeToEpoch -DateTime ($now.AddHours(1))
      $payloadTable = [ordered]@{sub = $ClientId; jti = ([System.Guid]::NewGuid()).ToString(); iss = $ClientId; aud = $IdentityServiceUri.TrimEnd('/') + "/connect/token"; nbf = $notBefore; exp = $futureEpochTime; iat = $currentEpochTime }
      $payload = $payloadTable | ConvertTo-Json -Compress | ConvertTo-Base64UrlEncodedString
      $jwtPlainText = "{0}.{1}" -f $header, $payload
      $jwtSig = New-JwtRsaSignature -JsonWebToken $jwtPlainText -SigningCertificate $SigningCertificate
      $ClientAssertion = "{0}.{1}" -f $jwtPlainText, $jwtSig
      $RequestUri = $IdentityServiceUri.TrimEnd('/') + "/connect/token"
      $Body = @{
          grant_type            = 'client_credentials'
          scope                 = $Scope
          username              = '{username}'
          client_assertion_type = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
          client_assertion      = $ClientAssertion
      }
      $Response = Invoke-WebRequest -Uri $RequestUri -Method 'POST' -Body $Body
      return (ConvertFrom-Json $Response).access_token
  }
}

function New-JwtRsaSignature {
  [CmdletBinding()]
  [OutputType([string])]
  Param(
      [System.Security.Cryptography.X509Certificates.X509Certificate2]$SigningCertificate,
      [String]$JsonWebToken
  )
  PROCESS {
      'Calling method: New-JwtRsaSignature' | Write-Debug
      $rsaSigFormatter = [System.Security.Cryptography.RSAPKCS1SignatureFormatter]::new()
      $rsaSigFormatter.SetKey($SigningCertificate.PrivateKey)
      $rsaSigFormatter.SetHashAlgorithm("SHA256")
      [byte[]]$message = [System.Text.Encoding]::UTF8.GetBytes($JsonWebToken)
      $shaAlg = [System.Security.Cryptography.SHA256]::Create()
      [byte[]]$messageDigest = $shaAlg.ComputeHash($message)
      $sigBytes = $rsaSigFormatter.CreateSignature($messageDigest)
      return ConvertTo-Base64UrlEncodedString -Bytes $sigBytes
  }
}

function ConvertTo-Base64UrlEncodedString {
  [CmdletBinding()]
  [OutputType([string])]
  Param (
      [Parameter(Position = 0, ParameterSetName = "String", Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
      [string]$InputString,

      [Parameter(Position = 1, ParameterSetName = "Byte Array", Mandatory = $false, ValueFromPipeline = $false, ValueFromPipelineByPropertyName = $false)]
      [byte[]]$Bytes
  )
  PROCESS {
      [string]$base64UrlEncodedString = ""

      if ($PSBoundParameters.ContainsKey("Bytes")) {
          $output = [Convert]::ToBase64String($Bytes)
          $output = $output.Split('=')[0] # Remove any trailing '='s
          $output = $output.Replace('+', '-') # 62nd char of encoding
          $output = $output.Replace('/', '_') # 63rd char of encoding
          $base64UrlEncodedString = $output

      }
      else {
          $encoder = [System.Text.UTF8Encoding]::new()
          [byte[]]$inputBytes = $encoder.GetBytes($InputString)
          $base64String = [Convert]::ToBase64String($inputBytes)
          [string]$base64UrlEncodedString = ""
          $base64UrlEncodedString = $base64String.Split('=')[0] # Remove any trailing '='s
          $base64UrlEncodedString = $base64UrlEncodedString.Replace('+', '-'); # 62nd char of encoding
          $base64UrlEncodedString = $base64UrlEncodedString.Replace('/', '_'); # 63rd char of encoding
      }
      return $base64UrlEncodedString
  }
}

function Convert-DateTimeToEpoch {
  [CmdletBinding()]
  [OutputType([System.Int64])]
  Param(
      [Parameter(Mandatory)]
      [DateTime]$DateTime
  )
  PROCESS {
      'Calling method: Convert-DateTimeToEpoch' | Write-Debug
      $dtut = $DateTime.ToUniversalTime()
      [TimeSpan]$ts = New-TimeSpan -Start  (Get-Date "01/01/1970") -End $dtut
      [Int64]$secondsSinceEpoch = [Math]::Floor($ts.TotalSeconds)
      return $secondsSinceEpoch
  }
}

$cert = (Get-ChildItem -path 'Cert:\*23BA1FFD6E83B92529317F80B55CFADA00877E4A' -Recurse)[0]
Get-IdentityServiceToken -IdentityServiceUri "https://identity.avepointonlineservices.com" -Scope cloudgovernance.fullcontrol.all -ClientId '{clientId}' -Cert $cert

Client secret as a credential:

function Get-IdentityServiceToken {
  [CmdletBinding()]
  [OutputType([string])]
  Param(
      [Parameter(Mandatory)]
      [string]$IdentityServiceUri,
      [Parameter(Mandatory)]
      [string]$Scope,
      [Parameter(Mandatory)]
      [string]$ClientId,
      [Parameter(Mandatory)]
      [string]$ClientSecret
  )
  PROCESS {
      'Calling method: Get-IdentityServiceToken' | Write-Debug
      $RequestUri = $IdentityServiceUri.TrimEnd('/') + "/connect/token"
      $Body = @{
          grant_type            = 'client_credentials'
          scope                 = $Scope
          username              = '{username}'
          client_id = $ClientId
          client_secret      = $ClientSecret
      }
      $Response = Invoke-WebRequest -Uri $RequestUri -Method 'POST' -Body $Body
      return (ConvertFrom-Json $Response).access_token
  }
}

Get-IdentityServiceToken -IdentityServiceUri "https://identity.avepointonlineservices.com" -Scope cloudgovernance.fullcontrol.all -ClientId '{clientId}' -ClientSecret '**'

You can find more information on what is possible with AvePoint Cloud Governance API here, as well as the coding details and examples.

REST API

Refer to the instructions below to get started with AvePoint Cloud Governance REST API.

In the AvePoint Cloud Governance API, you can see the supported methods. Access the API URL according to the environment you are using.

AvePoint Cloud Governance Environment	API URL (End User Level APIs)	API URL (System Level APIs)
The production environment for commercial use	https://go-api.avepointonlineservices.com	https://go-api.avepointonlineservices.com/admin
The production environment for U.S. Government Public Sector	https://governance-api-us-gov.avepointonlineservices.com	https://governance-api-us-gov.avepointonlineservices.com/admin
The Insider environment – the East US (Virginia) data center	https://insider-governance-api-us-east.avepointonlineservices.com	https://insider-governance-api-us-east.avepointonlineservices.com/admin
The Insider environment – the North Europe (Ireland) data center	https://insider-governance-api-north-europe.avepointonlineservices.com	https://insider-governance-api-north-europe.avepointonlineservices.com/admin

Choose one of the following methods to authenticate with AvePoint Cloud Governance API:

Authentication via a client ID and client secret
1. Navigate to System settings >API authentication profiles and click Create on the ribbon.
2. Enter a name for the profile.
3. Configure a duration for the client secret. The start time is the profile created time. Enter a number in the text box and select Days, Weeks, Months, or Years as the unit of time.
4. Define the services that can be called using this Cloud Governance API access token.
5. Click Save to save your configurations.
6. The Note window appears displaying the API authentication details. Click the Copy button to copy the client secret to your clipboard.
  
  NOTE
  The client secret will only be displayed one time, and you cannot retrieve it after you close the window.

Authenticate via Microsoft 365 single sign-on

This authentication method requires an access token and the access token will expire in one hour.

Access {API URL}/auth/token/user via your web browser. For example, https://go-api.avepointonlineservices.com/auth/token/user.

Refer to the information in the table below to choose the API URL.

AvePoint Cloud Governance Environment	API URL (End User Level APIs)	API URL (System Level APIs)
The production environment for commercial use	https://go-api.avepointonlineservices.com	https://go-api.avepointonlineservices.com/admin
The production environment for U.S. Government Public Sector	https://governance-api-us-gov.avepointonlineservices.com	https://governance-api-us-gov.avepointonlineservices.com/admin
The Insider environment – the East US (Virginia) data center	https://insider-governance-api-us-east.avepointonlineservices.com	https://insider-governance-api-us-east.avepointonlineservices.com/admin
The Insider environment – the North Europe (Ireland) data center	https://insider-governance-api-north-europe.avepointonlineservices.com	https://insider-governance-api-north-europe.avepointonlineservices.com/admin/index.html

On the Microsoft 365 sign-in page, sign in with your Microsoft 365 account.

NOTE
Make sure the account has been added to AvePoint Online Services and has the subscription for AvePoint Cloud Governance.

You can see an access token, a refresh token, and user information. The following is an example of the response:

{
  "access_token": "eyJhbGci…",
  "refresh_token": "eyJhbGci…",
  "user": {
    "userPrincipalName": "user's principal name",
    "displayName": "user's display name",
    "aadObjectId": "user's object ID in Microsoft Entra"
  },
  "duration": 3600
}

Authentication via an app registered in AvePoint Online Services

Go to the AvePoint Online Services > Administration > App registration page to register an app for AvePoint Cloud Governance. For details, refer to Configure App Registrations.

See the examples below for using the authentication.
- Authentication via a client ID and client secret
  
  The following is an example of the request that contains the required parameters for authentication: clientid, clientSecret, and userPrincipalName.
  
  NOTE
  The value of the userPrincipalName parameter is the login name of a delegated user that will be used to invoke the AvePoint Cloud Governance API. Make sure the user’s account has been added to AvePoint Online Services and has a subscription for AvePoint Cloud Governance.
  POST /tasks/my HTTP/1.1 Host: go-api.avepointonlineservices.com clientId: ceb5e… clientSecret: jLMX+… userPrincipalName: someone@contoso.com
- Authentication via Microsoft single sign-on
  
  Add a header in the request. The header name is Authorization, and the header value is Bearer {access token}. The following is an example:
  GET /tasks/my HTTP/1.1 Host: go-api.avepointonlineservices.com Authorization: Bearer eyJhbGciOi…
  If you want your application to receive the access token, you can append a redirect_uri query string. For example, https://go-api.avepointonlineservices.com/auth/token/user?redirect_uri=`{your application URL`}. AvePoint Cloud Governance API will post a form with the above information to your application URL.
- Authentication via an app registered in AvePoint Online Services
  
  Add a header in the request. The header name is Authorization, and the header value is Bearer {access token}. The following is an example:
  GET /tasks/my HTTP/1.1 Host: go-api.avepointonlineservices.com Authorization: Bearer eyJhbGciOi…

On this page

Settings

Configure Library Templates

Configure Service Templates

Appendix E - Integration with ServiceNow

Appendix G - Supported References in Email Templates

Appendix J - Custom Azure App Permissions for Using AvePoint Cloud Governance

AvePoint Cloud Governance API

C#

PowerShell

REST API

#AvePoint Cloud Governance API

#C#

#PowerShell

#REST API

AvePoint Cloud Governance API

C#

PowerShell

REST API