Altru authenticates via the Blackbaud ID secure authentication service. To use the API, you must have a Blackbaud ID. To gain access to a customer's environment, they must add you as a user. A single Blackbaud ID can connect to multiple Altru environments. For more information on adding and managing users, see Application Users in Altru Help.

In Altru, system roles control which features and records a user has access to. For example, users with the "Guest Services Manager" system role can manage the configuration of programs, events, and ticket sales. The system roles assigned to your Blackbaud ID control which features and data you can manipulate with the API.

• For your sandbox environment, your Blackbaud ID should have system administrator rights. This ensures you can enable design mode, access feature metadata, and more.
• For integrations that connect to a customer's live instance of Altru, the customer must assign system roles that grant access to all features that you wish to manipulate with the API. Altru customers use predefined system roles and do not have system administrator rights.

For more information, see System Roles in Altru Help.

For OData and SOAP API connections, Altru requires authentication via non-interactive "proxy" users and personal access tokens (PATs) These differ from traditional Altru users in that they require programmatic access to the database but don't need to sign in and perform tasks within the application itself.

Proxy users:

• inherit the same system roles as their linked proxy owners
• only need to authenticate every 365 days
• authenticate via PATs instead of passwords

Altru supports the use of proxy users for the following endpoints: ~/ODataQuery.ashx, ~/AppFxWebService.asmx, ~/vpp/bizops, and ~/util/DataList.ashx.

To learn how to add and manage proxy users, generate PATs, and assign system roles, see Non-Interactive Users in Altru Help.

The below example shows a Blackbaud Partner whose Blackbaud ID has access to three Altru environments:

The Infinity Web Services API uses a request-response pattern that consists of request-response pairs. An operation is called on the proxy, the request is passed to the operation, and a reply is received. Each request and reply object type is tailored to the type of operation.

The code sample below shows how to use the Blackbaud.AppFx.WebAPI.ServiceProxy to communicate with an Altru database and retrieve user information. It follows these steps:

1. To authenticate via the Blackbaud.AppFx.WebAPI.ServiceProxy, we use System.Net.ICredentials to set credentials for the web service.
2. To identify our custom application within Altru, we use ClientAppInfoHeader to set the application name (ClientAppName) and specify the intended Altru database (REDatabaseToUse).
3. To grab user information, we package a request (CurrentUserInfoGetRequest) that includes _clientappinfoheader and receive a response (CurrentUserInfoGetReply).

Private Shared _appFx As Blackbaud.AppFx.WebAPI.ServiceProxy.AppFxWebService
'You will need to set credentials for the web service.
Private Shared _myCred As System.Net.ICredentials
'ClientAppInfoHeader will be used to hold the client application name that identifies your custom client software for auditing purposes within the Infinty database.  It also holds a database identifier to help point to the correct database.
Private Shared _clientAppInfoHeader As Blackbaud.AppFx.WebAPI.ServiceProxy.ClientAppInfoHeader

Public Shared Function ValidateUser(ByVal applicationURL As String, ByVal userName As String, ByVal token As String, ByVal dbName As String) As Boolean
  Dim IsUserAbleToMakeRequest As Boolean = False
  Dim currentUserInfoGetRequest As New Blackbaud.AppFx.WebAPI.ServiceProxy.CurrentUserInfoGetRequest
  Dim currentUserInfoGetReply As New Blackbaud.AppFx.WebAPI.ServiceProxy.CurrentUserInfoGetReply
  Try
    'Display hourglass during appfx web service calls
    Cursor.Current = Cursors.WaitCursor
    Cursor.Show()

    'Instantiate the proxy to the Infinity application
    _appFx = New Blackbaud.AppFx.WebAPI.ServiceProxy.AppFxWebService
    _myCred = GetNetworkCredentials(userName, token)
    _appFx.Credentials = _myCred
    _appFx.Url = applicationURL

    _clientAppInfoHeader = New Blackbaud.AppFx.WebAPI.ServiceProxy.ClientAppInfoHeader
    _clientAppInfoHeader.ClientAppName = "AltruPATUtility"
    _clientAppInfoHeader.REDatabaseToUse = dbName

    currentUserInfoGetRequest.ClientAppInfo = _clientAppInfoHeader
    currentUserInfoGetReply = _appFx.CurrentUserInfoGet(currentUserInfoGetRequest)

    If currentUserInfoGetReply IsNot Nothing Then
    Return True
    End If
    Catch ex As Exception
      Throw ex
    Finally
    'Hide hourglass after api call
    currentUserInfoGetRequest = Nothing
    currentUserInfoGetReply = Nothing
    Cursor.Current = Cursors.Default
    Cursor.Show()
    End Try
    Return IsUserAbleToMakeRequest
    End Function
    Public Shared Function GetNetworkCredentials(ByVal userName As String, ByVal passWord As String) As System.Net.ICredentials
      Dim securelyStoredUserName, securelyStoredPassword As String
      securelyStoredUserName = userName
      securelyStoredPassword = passWord
      Dim NetworkCredential As New System.Net.NetworkCredential(securelyStoredUserName, securelyStoredPassword)
      Return NetworkCredential
    End Function

Example result: