Creating an authentication hash

Note

If you’re looking for the old version with encryption keys, see the Creating an authentication hash V2

With Corporate User V3 we will be migrating to token authentication based endpoints instead of the traditional encryption keys of V2.

Note

When calling the endpoints remember to prepend the Base URL of your AnnA Environment, i.e. https://learning.anna.center/

How to get the auth token

To use the corporate user v3 api, it is required to authenticate first using the GetToken endpoint. The token that is inside the data property will be used in the Authorization header with “Bearer ” prefix.

Endpoint: REST/Credentials/GetToken

Request body:

{
  "hash": "COMPANY_HASH",
  "user": "USER_LOGIN",
  "pass": "USER_PASSWORD"
}

Response:

{
  "success": true,
  "message": "…",
  "data": {
    "Token": "JWT_TOKEN",
    "ExpiresIn": "EXPIRATION_TIME"
  }
}

---

Below are the endpoints of V3 that you can call after getting the auth token

Generate User Hash

Generates an authentication hash for the informed user (USER_ID)

Endpoint: REST/AnnACorporate/User/UserHash

Request body:

{
  "hash": "YOUR_COMPANY_HASH",
  "userId": "USER_ID",
  "startService": "START_SERVICE"
}

Response (success):

{
  "success": true,
  "message": "User Hash generated successfully",
  "accessData": {
    "Hash": "USER_HASH",
    "ChatURL": "CHAT_URL_WITH_USER_HASH",
    "EmbeddedURL": "EMBEDDED_URL_WITH_USER_HASH",
    "Expires": "EXPIRATION_DATETIME" // YYYYMMDDhhmmss
  }
}

Response (failure):

{
  "success": false,
  "message": "User COMPANY_HASH@USER_ID is inactive."
}

Force Generate User Hash

Create or update an user with the values from USER_ID and USER_NAME, and generates an authentication hash

Endpoint: REST/AnnACorporate/User/UserHashForced

Request body:

{
  "hash": "YOUR_COMPANY_HASH",
  "userId": "USER_ID",
  "userName": "USER_NAME",
  "startService": "START_SERVICE"
}

Response (success):

{
  "success": true,
  "message": "User Hash generated successfully",
  "accessData": {
    "Hash": "USER_HASH",
    "ChatURL": "CHAT_URL_WITH_USER_HASH",
    "EmbeddedURL": "EMBEDDED_URL_WITH_USER_HASH",
    "Expires": "EXPIRATION_DATETIME" // YYYYMMDDhhmmss
  }
}

Inactivate User

Inactivates the informed user (USER_ID)

Endpoint: REST/AnnACorporate/User/Inactivate

Request body:

{
  "hash": "COMPANY_HASH",
  "userId": "USER_ID"
}

Response:

{
  "success": true,
  "message": "User COMPANY_HASH@USER_ID inactivated successfully"
}

Messenger Structure

Returns a json providing a list of departments (alias and name) and the list of channels for each department of the company

Endpoint: REST/AnnACorporate/Messenger/Structure

Request body:

{
  "hash": "COMPANY_HASH"
}

Response:

{
  "success": true,
  "message": "…",
  "structure": {
    "CompaniesHash": "…",
    "CompaniesName": "…",
    "Departments": []
  }
}

Messenger Alert Counter

Returns a json indicating the number of request with “Open” status that are pending a response for the user specified in the variable USER_ID or by the set of values in the variables MESSENGER_UNIQUE_DOC_TYPE and MESSENGER_UNIQUE_DOC_VALUE

You can also filter the result by department, channel, initial date and final date using the variable MESSENGER_FILTER

Endpoint: REST/AnnACorporate/Messenger/AlertCounter

Request body:

{
  "hash": "COMPANY_HASH",
  "userId": "USER_ID",
  "userDocType": "UNIQUE_DOC_TYPE",
  "userDocValue": "UNIQUE_DOC_VALUE",
  "messengerFilters": {
    "departmentAlias": "",
    "channelAlias": "",
    "dataIni": "",
    "dataFim": "",
    "status": "",
    "pendentes": ""
  }
}

Response:

{
  "success": true,
  "message": "…",
  "alertCounter": 1
}

Messenger Requests

Returns a json with a collection of request for the user specified in the USER_ID variable or by the set of values in the MESSENGER_UNIQUE_DOC_TYPE and MESSENGER_UNIQUE_DOC_VALUE variables, containing the following data: Department, channel, request description, opening date, protocol, status (open/closed), a flag indicating if it is pending a response from the user, and a link to view the specific request.

You can also filter the result by department, channel, start date, end date, status (A-open, E-closed), and pendings (S/N - pending a response from the user or not) using the variable MESSENGER_FILTER

Endpoint: REST/AnnACorporate/Messenger/Requests

Request body:

{
  "hash": "",
  "userId": "",
  "userDocType": "",
  "userDocValue": "",
  "messengerFilters": {
    "departmentAlias": "",
    "channelAlias": "",
    "dataIni": "",
    "dataFim": "",
    "status": "",
    "pendentes": ""
  }
}

Response:

{
  "success": true,
  "message": "…",
  "userRequests": []
}

Messenger Link

Returns a json with the link to visualize the request full content of the messaging system for the user specified in the USER_ID variable or by the set of values in the MESSENGER_UNIQUE_DOC_TYPE and MESSENGER_UNIQUE_DOC_VALUE variables

Endpoint: REST/AnnACorporate/Messenger/Link

Request body:

{
  "hash": "",
  "userId": "",
  "userDocType": "",
  "userDocValue": ""
}

Response:

{
  "success": true,
  "message": "…",
  "messengerLink": "…"
}

Examples

C#/.NET

Tip

For .NET Framework and .NET applications you may want to use the AnnA.Services package available at: https://www.nuget.org/packages/AnnA.Services

var httpClient = new HttpClient
{
    BaseAddress = new Uri("YOUR_ANNA_BASE_URL")
};

var result = await httpClient.PostAsJsonAsync("REST/Credentials/GetToken", new
{
    hash = "COMPANY_HASH",
    user = "USER_LOGIN",
    pass = "USER_PASSWORD"
});

var tokenResponse = await result.Content.ReadFromJsonAsync<GetTokenResponse>();

httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", tokenResponse?.Data.Token);

var corporateApi = new CorporateUserApi(httpClient);

// Sample purposes only
var userHashResponse = await corporateApi.GenerateUserHash();
var fUserHashResponse = await corporateApi.ForceGenerateUserHash();
var inactivateUserResponse = await corporateApi.InactivateUser();
var messengerAlertCounterResponse = await corporateApi.MessengerAlertCounter();
var messengerRequestsResponse = await corporateApi.MessengerRequests();
var messengerLinkResponse = await corporateApi.MessengerLink();

Models/GetTokenResponse.cs

  public class GetTokenResponse
  {
    [JsonPropertyName("success")]
    public bool Success { get; set; }

    [JsonPropertyName("message")]
    public string Message { get; set; } = string.Empty;

    [JsonPropertyName("data")]
    public TokenData Data { get; set; } = new();
  }

  public class TokenData
  {
    [JsonPropertyName("Token")]
    public string Token { get; set; } = string.Empty;

    [JsonPropertyName("ExpiresIn")]
    public string ExpiresIn { get; set; } = string.Empty;
  }

CorporateUserApi.cs

public class CorporateUserApi(HttpClient httpClient)
{
  public async Task<string> GenerateUserHash()
  {
      var result = await httpClient.PostAsJsonAsync("REST/AnnACorporate/User/UserHash", new
      {
      hash = "COMPANY_HASH",
      userId = "USER_ID",
      startService = "START_SERVICE"
      });

      return await result.Content.ReadAsStringAsync();
  }

  public async Task<string> ForceGenerateUserHash()
  {
      var result = await httpClient.PostAsJsonAsync("REST/AnnACorporate/User/UserHashForced", new
      {
          hash = "COMPANY_HASH",
          userId = "USER_ID",
          userName = "USER_NAME",
          startService = "START_SERVICE"
      });

      return await result.Content.ReadAsStringAsync();
  }

  public async Task<string> InactivateUser()
  {
      var result = await httpClient.PostAsJsonAsync("REST/AnnACorporate/User/Inactivate", new
      {
          hash = "COMPANY_HASH",
          userId = "USER_ID",
      });

      return await result.Content.ReadAsStringAsync();
  }

  public async Task<string> MessengerStructure()
  {
      var result = await httpClient.PostAsJsonAsync("REST/AnnACorporate/Messenger/Structure", new
      {
          hash = "COMPANY_HASH",
      });

      return await result.Content.ReadAsStringAsync();
  }

  public async Task<string> MessengerAlertCounter()
  {
      var result = await httpClient.PostAsJsonAsync("REST/AnnACorporate/Messenger/AlertCounter", new
      {
          hash = "COMPANY_HASH",
          userId = "USER_ID",
          userDocType = "",
          userDocValue = "",
          messengerFilters = new
          {
              departmentAlias = "",
              channelAlias = "",
              dataIni = "01/01/2024",
              dataFim = "31/12/2024",
              status = "",
              pendentes = ""
          }
      });

      return await result.Content.ReadAsStringAsync();
  }

  public async Task<string> MessengerRequests()
  {
      var result = await httpClient.PostAsJsonAsync("REST/AnnACorporate/Messenger/Requests", new
      {
          hash = "COMPANY_HASH",
          userId = "WSGIU5555",
          userDocType = "",
          userDocValue = "",
          messengerFilters = new
          {
              departmentAlias = "",
              channelAlias = "",
              dataIni = "01/01/2024",
              dataFim = "31/12/2024",
              status = "",
              pendentes = ""
          }
      });

      return await result.Content.ReadAsStringAsync();
  }

  public async Task<string> MessengerLink()
  {
      var result = await httpClient.PostAsJsonAsync("REST/AnnACorporate/Messenger/Link", new
      {
          hash = "COMPANY_HASH",
          userId = "USER_ID",
          userDocType = "UNIQUE_DOC_TYPE",
          userDocValue = "UNIQUE_DOC_VALUE"
      });

      return await result.Content.ReadAsStringAsync();
  }

}