Admin API
Caution
Sample code provided in here is for demonstration and educational purposes only which provides customers with programming information regarding the products and is not intended for use in a production environment. All production code should always follow development best practices. All sample code here is supplied "AS IS" without any warranties or support.
This section describes how to use the admin API, how to retrieve a access token and how to call the API.
The provided C# code samples below uses HttpClient to make the REST calls.
Warning
A common mistake when using HttpClient is to use multiple instances of the
HttpClient. You should reuse the same instance within an application.
Authenticate
The admin API authentication is not based on a user token that expires after a certain amount of time. The authorization header for all admin API calls has a bearer token that is created using the symmetric key (admin, auth, snapshot) and the relative path.
In C# a way is to extend AuthenticationHeaderValue, below is an example of how
this can be done:
using System;
using System.Net.Http.Headers;
using System.Security.Cryptography;
using System.Text;
namespace Demo.AdminApi
{
public class BearerAuthenticationHeaderValue : AuthenticationHeaderValue
{
public BearerAuthenticationHeaderValue(string symmetricKey, string relativeUri)
: base("Bearer", GetBearerToken(symmetricKey, relativeUri))
{
}
private static string GetBearerToken(string symmetricKey, string relativeUri)
{
byte[] encodedPath = Encoding.ASCII.GetBytes(relativeUri);
byte[] byteKey = Convert.FromBase64String(symmetricKey);
HMACSHA512 sha = new HMACSHA512(byteKey);
byte[] hash = sha.ComputeHash(encodedPath);
string hashString = Convert.ToBase64String(hash);
string bearerToken = hashString.Split('=')[0];
bearerToken = bearerToken.Replace('+', '-');
bearerToken = bearerToken.Replace('/', '_');
return bearerToken;
}
}
}
In PowerShell an authentication header can be created with a function that looks like the one below:
Download get-authorization-header.ps1
function GetAuthorizationHeader ($key, $path){
$encodedPath = [Text.Encoding]::ASCII.GetBytes($path)
$sha = New-Object System.Security.Cryptography.HMACSHA512
$sha.key = [Convert]::FromBase64String($key)
$hash = $sha.ComputeHash($encodedPath)
$hashString = [Convert]::ToBase64String($hash)
$bearerToken = $hashString.Split('=')[0]
$bearerToken = $bearerToken.Replace('+', '-')
$bearerToken = $bearerToken.Replace('/', '_')
return @{"Authorization" = ("Bearer", $bearerToken -join " ")}
}
Change Password
There is an API call to change password for a user. In order to run the API call, the email of the user, the auth symmetric key and the UoI-version of the user are all required.
In C# the following code would work as an example using the authentication header above.
public static void ChangePassword(string baseAddress, string authApiKey, string email, string password, string uoiVersion)
{
byte[] bytes = Encoding.Unicode.GetBytes(password);
SHA512Managed sha = new SHA512Managed();
byte[] hash = sha.ComputeHash(bytes);
sha.Dispose();
string passwordHash = string.Empty;
foreach (byte b in hash)
{
passwordHash += string.Format("{0:x2}", b);
}
string relativeUri = $"/identity/user/updatePassword?email={email}&password={passwordHash}";
HttpClient client = new HttpClient();
client.BaseAddress = new Uri(baseAddress);
client.DefaultRequestHeaders.Authorization = new BearerAuthenticationHeaderValue(authApiKey, relativeUri);
client.DefaultRequestHeaders.Add("SAs-UOIVersion", uoiVersion);
HttpResponseMessage response = client.PutAsync(relativeUri, null).Result;
response.EnsureSuccessStatusCode();
client.Dispose();
}
In PowerShell the following script can be used where the password is encrypted using
the encryption function in the ConfigTool. Use the function described above,
GetAuthorizationHeader to obtain an auth header when running the script.
$email = "admin@eurostep.com"
$password = "7bdb70e23007b241d9caff64af5463fb3e12d9152a4fc9bbddf019175f5ec418ea3c67606a9d03f44bdc5de17b8f49ca5511666eaca74a31cdd5bf51608c87af"
$key = "nCs5/VJHmEGIwVmmRJIK+Jj7tWgKNcNO2a0IRmjPZ+IN74ORU1IFwJpm/UvOA5svReASvk2QfqtqXA9aitZQRQ=="
$path = "/identity/user/updatePassword?email=$email&password=$password"
$uri = "http://localhost:5000" + $path
$headers = GetAuthorizationHeader $key $path
$headers.Add("SAs-UOIVersion", 1)
$response = Invoke-RestMethod -Method Put -Uri $uri -ContentType "application/json" -Headers $headers
Other C-sharp examples
Below is a collection of examples of using the admin API.
ReIndex The re-index function will do a re-indexation of all indexes in a certain space of ShareAspace Nova, the symmetric key used is the administration symmetric key.
public static void ReIndex(string baseAddress, string adminApiKey, string spaceId)
{
string relativeUri = $"/admin/reindex/{spaceId}";
HttpClient client = new HttpClient();
client.BaseAddress = new Uri(baseAddress);
client.DefaultRequestHeaders.Authorization = new BearerAuthenticationHeaderValue(adminApiKey, relativeUri);
HttpResponseMessage response = client.PostAsync(relativeUri, null).Result;
response.EnsureSuccessStatusCode();
client.Dispose();
}
RebuildAnIndex The re-index of one index will only re-index a specific index for a specific space, the symmetric key used is the administration symmetric key.
//
// MIT License
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of
// this software and associated documentation files (the "Software"), to deal in
// the Software without restriction, including without limitation the rights to
// use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
// the Software, and to permit persons to whom the Software is furnished to do so,
// subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
// FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
// COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
// IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
// CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
//
using System;
using System.IO;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
namespace Demo.AdminApi
{
public static partial class Program
{
public static void ChangePassword(string baseAddress, string authApiKey, string email, string password, string uoiVersion)
{
byte[] bytes = Encoding.Unicode.GetBytes(password);
SHA512Managed sha = new SHA512Managed();
byte[] hash = sha.ComputeHash(bytes);
sha.Dispose();
string passwordHash = string.Empty;
foreach (byte b in hash)
{
passwordHash += string.Format("{0:x2}", b);
}
string relativeUri = $"/identity/user/updatePassword?email={email}&password={passwordHash}";
HttpClient client = new HttpClient();
client.BaseAddress = new Uri(baseAddress);
client.DefaultRequestHeaders.Authorization = new BearerAuthenticationHeaderValue(authApiKey, relativeUri);
client.DefaultRequestHeaders.Add("SAs-UOIVersion", uoiVersion);
HttpResponseMessage response = client.PutAsync(relativeUri, null).Result;
response.EnsureSuccessStatusCode();
client.Dispose();
}
public static void ReIndex(string baseAddress, string adminApiKey, string spaceId)
{
string relativeUri = $"/admin/reindex/{spaceId}";
HttpClient client = new HttpClient();
client.BaseAddress = new Uri(baseAddress);
client.DefaultRequestHeaders.Authorization = new BearerAuthenticationHeaderValue(adminApiKey, relativeUri);
HttpResponseMessage response = client.PostAsync(relativeUri, null).Result;
response.EnsureSuccessStatusCode();
client.Dispose();
}
public static void RebuildAnIndex(string baseAddress, string adminApiKey, string spaceId, string indexId)
{
string relativeUri = $"/admin/reindex/{spaceId}/{indexId}";
HttpClient client = new HttpClient();
client.BaseAddress = new Uri(baseAddress);
client.DefaultRequestHeaders.Authorization = new BearerAuthenticationHeaderValue(adminApiKey, relativeUri);
HttpResponseMessage response = client.PostAsync(relativeUri, null).Result;
response.EnsureSuccessStatusCode();
client.Dispose();
}
Upload It is possible to upload files to the collection using the upload api call. The symmetric key used is the task symmetric key.
public static void Upload(string baseAddress, string taskApiKey, string path, string filePath)
{
string relativeUri = $"/system/upload/{path}";
HttpClient client = new HttpClient();
client.BaseAddress = new Uri(baseAddress);
client.DefaultRequestHeaders.Authorization = new BearerAuthenticationHeaderValue(taskApiKey, relativeUri);
using (FileStream file = new FileStream(filePath, FileMode.Open, FileAccess.Read))
{
StreamContent content = new StreamContent(file);
HttpResponseMessage response = client.PostAsync(relativeUri, content).Result;
response.EnsureSuccessStatusCode();
}
client.Dispose();
}
Download To download the files from collection use the download API call. The symmetric key used is the task symmetric key.
public static void Download(string baseAddress, string taskApiKey, string path, string filePath)
{
string relativeUri = $"/system/download/{path}";
HttpClient client = new HttpClient();
client.BaseAddress = new Uri(baseAddress);
client.DefaultRequestHeaders.Authorization = new BearerAuthenticationHeaderValue(taskApiKey, relativeUri);
Stream response = client.GetStreamAsync(relativeUri).Result;
using (FileStream file = new FileStream(filePath, FileMode.Create, FileAccess.Write))
{
response.CopyTo(file);
}
client.Dispose();
}
Download sample
The examples above are collected in a project that can be downloaded.