Skip to main content

​
About IVM

IVM provides industrial vending machines, smart lockers, and automated supply distribution hardware, managed through its SmartHub platform. The Serval integration connects to the IVM API (version 21.1) so your workflows can look up machines, locations, products, inventory levels, vend history, and reports. All requests flow through Serval’s authenticated proxy - nothing is installed on your IVM tenant. Authentication: Username and password (OAuth2 password grant against your SmartHub identity server). Serval exchanges your stored credentials for a short-lived access token on each request. Data sync: On-demand only. There is no background sync and no entity ingestion - workflows call the IVM API at the moment they run.

​
What the IVM integration enables

CapabilityDescription
Full IVM API accessThe generic “IVM API request” action exposes the full IVM API v21.1 surface (263 API paths spanning 366 operations), covering machines, machine users, locations, products, planograms, categories, portal users, enhanced lockers, smart screens, webhooks, vend history, restriction groups, and more.
Machine managementList vending machines, look up a machine by ID, and query machine types, status, authorization, purposes, and planograms.
Inventory and reportingAccess inventory levels, vend history, failed vends, delinquency reports, and the extensive reporting surface (43 standard report endpoints plus 17 custom report endpoints).
LocationsList and manage the locations where your machines are deployed.
Product catalogBrowse products, global products, chained products, categories, planograms, and planogram slots.
Bundled workflows: Inventory ManagementAn out-of-the-box bundle of four read-only workflows, all defaulting to no approval required: “List IVM Machines”, “Get IVM Machine by ID”, “List IVM Locations”, and “List IVM Products”.
Anything defined in the IVM API can be accessed through Serval.

​
Get your credentials

IVM does not offer a self-serve developer console for API credentials. Your IVM administrator (or IVM support) provisions an API user account for your tenant. You need four things before connecting: a username, a password, your tenant’s API URL, and your tenant’s SmartHub identity server URL.
1

Request an API user account

Contact your IVM account administrator or IVM support and ask them to provision a username and password authorized for IVM API access. See the IVM SmartHub platform page for more on the platform.
2

Collect your tenant URLs

Obtain your tenant’s API URL (for example, https://ivmapi.com) and your SmartHub identity server URL (for example, https://smarthubidentity.ivminc.com). Both must be HTTPS.
3

Confirm the account supports direct password sign-in

The account must be able to authenticate directly against the identity server with its username and password (the OAuth2 password grant).
4

Confirm API permissions

Make sure the account has permission for the data your workflows need. At minimum it should be able to read machine types, machines, and locations - that is what Serval’s connection checks exercise.
SSO-only portal logins (for example, Microsoft Entra ID federation) are not API credentials and will not work. The account must support direct username and password authentication.

​
Connect in Serval

1

Open the IVM connect form

In Serval, add a new IVM connection to open the credential form. All four fields are required - if you leave the API URL, Identity Server URL, or Username blank, the form flags the field with “This field is required” when you save.
2

Enter the API URL

The base URL of your IVM API tenant - the field shows https://ivmapi.com as an example. It must start with https://. The URL’s host becomes the connection’s display name in Serval.
3

Enter the Identity Server URL

The base URL of your SmartHub identity server - the field shows https://smarthubidentity.ivminc.com as an example. It must start with https://. Enter the base URL only - Serval builds the token endpoint itself.
4

Enter the Username

Your IVM API username. After saving, it displays masked, with only the last 4 characters visible.
5

Enter the Password

Your IVM API password. This is a password-style field, also masked after saving. Unlike the other fields, a blank password is caught at save time by the server, which reports “Invalid IVM configuration: password is required” (the message is lowercase).
6

Save the connection

Submit the form. Server-side validation failures appear as a message starting with “Failed to install integration: Invalid IVM configuration” followed by the specific problem - for example, “API URL must start with https://” or “Identity Server URL must start with https://” if either URL is not HTTPS.
When you later edit the connection, any field left blank (or left showing its masked bullet placeholder) keeps its previously stored value. To rotate just the password, use the edit control next to the Password field, enter the new value, and save - everything else is preserved.

​
Verifying the connection

Serval runs three health checks against your IVM tenant. Each one goes through the full authentication path, so a passing check confirms both your credentials and your URLs. Saving a change on the connection’s settings page automatically re-runs the enabled health checks.
  • Validate IVM API Connection - reads the list of machine types in your tenant. Success shows “Successfully connected to IVM API.” Failure shows “Unable to connect to IVM API. Please verify your credentials and API URL are correct.”
  • List Machines - lists a small sample of machines. Success shows “Successfully listed machines. Found [number] machines in IVM.” (the wording adjusts to “machine” when there is exactly one). Failure shows “Unable to list machines. Please verify your credentials have the necessary permissions.”
  • List Locations - lists a small sample of locations. Success shows “Successfully listed locations. Found [number] locations in IVM.” (singular when there is exactly one). Failure shows “Unable to list locations. Please verify your credentials have the necessary permissions.”
If all three checks pass but a workflow still fails, the most likely cause is permissions: the health checks only verify read access to machine types, machines, and locations. Ask your IVM administrator to confirm the API account can access the other areas your workflows use, such as reports, products, or vend history.

​
Gotchas and troubleshooting

Authentication uses the OAuth2 password grant against the SmartHub identity server, which requires direct username and password sign-in. Accounts that only sign in through federated SSO cannot authenticate this way. If connection checks fail with valid-looking portal credentials, request a dedicated API username and password from your IVM administrator.
Serval builds the token endpoint itself from the Identity Server URL (trailing slashes are trimmed automatically). If you paste the full token endpoint URL instead of the base URL, the token path gets appended a second time and every authentication attempt fails.
Serval rejects any API URL or Identity Server URL that does not start with https://. On initial connect the error names the field (“API URL must start with https://” or “Identity Server URL must start with https://”); when editing, the same check runs on any new value you provide, and the settings page reports “Failed to update configuration” if it fails.
When editing the connection, a blank field (or one left showing its masked bullet placeholder) retains the previously stored value. This applies to all four fields, including the URLs. This is convenient for rotating a single credential, but it also means you cannot “clear” a field by emptying it - enter a new value to change it.
Both the username and the password are stored as secrets. When you reopen the connection’s settings, each shows as bullet characters plus its last 4 characters. The password sits behind an edit control (a pencil or “Replace” button) you click before typing a new value; the username appears as a directly editable field pre-filled with the masked value. Either way, saving the masked value untouched leaves the stored credential intact - this is expected.
The connection’s domain and display name in Serval come from the API URL’s host. If you update the API URL, the connection is re-keyed to the new host.
The token request Serval sends includes only the username, password, and standard grant parameters (it requests the api1 and offline_access scopes) - it does not send a client ID or client secret. If your identity server requires a client ID for the password grant, this integration cannot supply one; ask IVM support to allow the grant without one. Token failures surface in workflow runs as “failed to authenticate with IVM”. Token requests also time out after 30 seconds, so a slow or unreachable identity server produces the same authentication error.
Serval’s proxy only sends requests to subdomains of ivminc.com (such as smarthubidentity.ivminc.com) and to hosts ending in ivmapi.com. The bare ivminc.com domain with no subdomain is not allowed. If your tenant uses a different domain, requests will be blocked - contact Serval support.
Need help? Contact support@serval.com for assistance with your IVM integration.