ETO Software's API allows social impact organizations to create functional applications or integrations through remote execution. Authentication is performed by making REST-based web service requests with an active ETO account. Your ETO solution will need the API feature enabled. To enable this feature, or if you are interested in using our test environment, please reach out to your Account Manager directly or via accountmanagement@bonterratech.com.
Accessing the API
Your URL will determine which API link you use.
For .com users, please use services.etosoftware.com/api-docs.
For .ca users, please use services.etosoftware.ca/api-docs.
For .au users, please use services.etosoftwareau.com/api-docs.
For .us users, please use services.etosoftware.us/api-docs.
On this page, you will find the available methods for each functional area of ETO.
Logging into the API
Logging into the API is a multi-step process. The first two steps are required to complete all other calls in the API. The third step is required to set the login to a specific program before performing calls. Before entering the API, it can be helpful to have your EnterpriseGUID and SiteID available. Your SiteID is easily found in your WhoAmI.
Your unique EnterpriseGUID can be found by logging into ETO, navigating to Marketplace > View Marketplace > Free Add-Ons link at the top, and clicking the View Details button beside Barcode Sync. The string of letters and numbers in the field on this page is your EnterpriseGUID.
Note: Copy and paste your EnterpriseGUID into a text editor (Notepad, Word, etc). Once you are logged into the API, logging into ETO will invalidate your API log in.
Step 1: Authentication - SSOAuthenticate
Navigate to the Authentication section. In this section, open the
POST | /API/Security.svc/SSOAuthenticate/ option. This POST method will authenticate the user account and requires the user email address and password.
To quickly populate the SSOAuthenticateWrapper field with the correct details, click the Example Value field to the right. In the Wrapper field, remove the additional values, leaving only Email and Password, as shown in the example below.
{
"security": {
"Email": "jessica@fake.com",
"Password": "ExamplePassword1!",
}
}Enter the username and password you use to log into ETO, and click "Try it out!" The Response will now populate. In the Response Body, copy the SSOAuthToken result value. You will need this for the second step of the login process.
Step 2: Authentication - SSO Site Login
Select the GET | /API/Security.svc/SSOSiteLogin/{SiteID}/{enterpriseGuid}/{AuthToken}/{CurrentTimeZoneOffset} option. This logs you into a specific site and requires a SiteID, EnterpriseGUID, AuthToken, and a CurrentTimeZoneOffset. The AuthToken is the SSOAuthToken from the previous step.
Enter the four required fields and click "Try it out!" The response now includes a Response Body, which is the SecurityToken. This is needed for all other calls inside the API.
Step 3: Authentication - Update Current Program
Select the POST | /API/Security.svc/UpdateCurrentProgram/ option. This option will log you into a specific program and needs EnterpriseGUID, SecurityToken, and UpdateCurrentProgramWrapper, completed with a ProgramID.
Note: The SSOAuthToken and SecurityToken will no longer be valid (will expire) if one of the following happens:
The account you are using to authenticate within the API then logs directly into the ETO UI. This is considered a concurrent log in and the first log in (the API authentication) will be kicked off.
You are idle for the amount of time that is set as the session time out limit, which is set on a site-by-site basis with the 'security token recycle interval' setting in ETO.
If either of the above happens, you will get an authentication error the next time you go to do something with the API. At that point you will need to start from the beginning of this article in order to start a new session with new tokens.