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: Your IVM API username and password (OAuth2 password grant against your SmartHub identity server). Serval presents IVM’s standard OAuth client to the identity server for you, so those are the only credentials you supply. Serval exchanges them for a short-lived access token and reuses it until shortly before it expires. 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

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. 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

Email support@ivminc.com 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

Confirm which environment you are connecting to and use the matching pair of URLs. 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.
You do not need an OAuth client ID or client secret. IVM’s API documentation publishes a single OAuth client that is the same for every customer, and Serval presents it to the identity server automatically on every token request. It is not a per-customer credential, so there is nothing to request and nothing to enter.
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. Only the API URL, Identity Server URL, Username, and Password are required - if you leave one of the first three blank, the form flags the field with “This field is required” when you save. Client ID, Client Secret, and Scope are optional and should be left blank.
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

Leave Client ID, Client Secret, and Scope blank

Serval fills all three in for you: IVM’s standard OAuth client, and the api1 offline_access scope IVM requires. Fill them in only if IVM tells you your tenant has a dedicated OAuth client or a different scope - and if you set a Client Secret you must also set a Client ID, or the save is rejected with “client secret requires a client ID”.
7

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, and fail with invalid_grant. If connection checks fail with valid-looking portal credentials, request a dedicated API username and password from support@ivminc.com.
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 every field, including the URLs and the optional Client ID, Client Secret, and Scope. 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. To go back to the standard scope, type api1 offline_access rather than blanking the field.
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.
A failed health check shows “failed to authenticate with IVM” followed by the identity server’s own error and, when it provides one, error_description. The three you are likely to see mean different things:Token requests time out after 30 seconds, so a slow or unreachable identity server surfaces as an authentication error too.
Serval caches each connection’s access token for the lifetime the identity server reports, refreshing it five minutes before expiry. A token issued with no stated lifetime is used once and not cached. Changing anything the token was minted under - username, password, client ID, client secret, or scope - retires the cached token immediately, so a rotation takes effect on the next call rather than when the old token would have expired.
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.