Skip to main content

​
About Snipe-IT

Snipe-IT is an open-source IT asset management (ITAM) platform for tracking hardware, licenses, accessories, consumables, and components. The Serval integration connects to your own Snipe-IT instance - cloud-hosted (such as your-company.snipe-it.io) or fully self-hosted on any domain - using a personal API key generated inside Snipe-IT. Once connected, Serval workflows and Catalyst can work with your full Snipe-IT inventory: asset checkout and checkin, user lookups, license seat management, audits, and more. See the Snipe-IT documentation for product details. Authentication: API key (Bearer token) - your instance domain plus a personal API key created in Snipe-IT. Data sync: On-demand only. Serval contacts your Snipe-IT instance when a workflow or Catalyst runs an action - there is no background sync or scheduled import. Health checks confirm the connection stays healthy.

​
What the Snipe-IT integration enables

Anything defined in the Snipe-IT API can be accessed through Serval.

​
Get your credentials

Serval connects with a personal API key created inside your Snipe-IT instance. The key acts with the permissions of the user who creates it, so use an account that can view (and, if your workflows write data, manage) everything your workflows will touch. Snipe-IT’s own guide is at Authenticating with the Snipe-IT API.
1

Log in to your Snipe-IT instance

For example, https://your-company.snipe-it.io, or your self-hosted domain.
2

Open Manage API Keys

Click your account dropdown in the top-right corner and select Manage API Keys.
3

Create a token

Click Create New Token and give it a descriptive name (for example, “Serval Integration”).
4

Copy the key immediately

Keep it somewhere safe until you have pasted it into Serval.
Snipe-IT shows the API key only once. If you lose it, you must generate a new one.
The key inherits the permissions of the user who created it. A key from an under-permissioned account will connect but fail the permission health checks below.

​
Connect in Serval

1

Open the Snipe-IT connect form

In Serval, open the Snipe-IT integration and start a new connection.
2

Enter your Snipe-IT URL (required)

Enter your instance base domain, for example your-company.snipe-it.io. As the helper text says, do not include /api/ or /v1/ paths. Leaving it empty shows “This field is required”. You can paste a full URL - Serval automatically strips https:// or http:// prefixes, trailing slashes, and trailing /api, /api/v1, or /v1 segments when saving.
3

Enter your API Key (required)

Paste the key you copied from Snipe-IT. The field hides the value as you type.
4

Save the connection

Saving the form does not test the key against Snipe-IT. Verification happens right afterward via the health checks below.
When editing an existing connection, the form pre-fills your saved Snipe-IT URL, and the API Key appears as a masked value (bullets plus the last 4 characters of the saved key) with a control to replace it. Leave the key untouched and the stored key is kept. Any field that reaches Serval blank also keeps its stored value - so you can rotate the key without re-typing the domain, or fix the domain without re-pasting the key.

​
Verifying the connection

After you connect, Serval runs three health checks against your instance:
  • Validate Snipe-IT API Connection - confirms your instance is reachable and the API key authenticates.
    • Success: “Successfully connected to Snipe-IT API.”
    • Failure: “Unable to connect to Snipe-IT API. Please verify your API key is valid and has the necessary permissions.”
  • List Users - confirms the key can read users and reports your user count.
    • Success: “Successfully listed users. Found [number] users in Snipe-IT.”
    • Failure: “Unable to list users. Please verify your API key has user read permissions.”
  • List Hardware Assets - confirms the key can read hardware assets and reports your asset count.
    • Success: “Successfully listed hardware assets. Found [number] total assets in Snipe-IT.”
    • Failure: “Unable to list hardware assets. Please verify your API key has hardware read permissions.”
Counts are filled in at runtime; when the total is 1, the message uses the singular “user” or “asset”.
If “Validate Snipe-IT API Connection” passes but “List Users” or “List Hardware Assets” fails, your key is valid but the Snipe-IT user who created it lacks read access to that resource. Grant that user the missing permission in Snipe-IT - permissions are evaluated live, so the check passes on the next run without re-entering the key.

​
Gotchas and troubleshooting

Submitting the form saves the connection without making a live call to Snipe-IT. A wrong or under-permissioned key only shows up afterward, when the health checks run. If a health check fails right after connecting, re-check the key rather than the form.
Enter just the base domain (for example, your-company.snipe-it.io). Serval auto-cleans common extras - https:// or http:// prefixes, trailing slashes, and trailing /api, /api/v1, or /v1 segments - but a URL that still contains /api/ or /v1/ in the middle of the path is rejected. The rejection surfaces only as a generic failure (such as “Failed to connect service” or “Failed to install integration”) without a specific explanation, so if connecting keeps failing, the URL is the first thing to fix.
Snipe-IT API keys act with the permissions of the user who created them. The “List Users” and “List Hardware Assets” health checks fail independently if that user lacks read access to those resources - create the key from an account whose permissions cover everything your workflows touch.
When editing the connection, the saved Snipe-IT URL is pre-filled and the API Key shows as a masked value (bullets plus the last 4 characters). An untouched key is never overwritten, and a field that reaches Serval blank - an emptied URL, or a key you started replacing but left empty - keeps its stored value. Serval re-runs the health checks automatically after you save an update.
Snipe-IT returns list results in pages: a total count plus one batch of rows per request, advanced with an offset rather than a cursor. Workflows that walk a large inventory must request successive pages, increasing the offset until the whole total has been covered - a single request will not return everything.
Need help? Contact support@serval.com for assistance with your Snipe-IT integration.