> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Snipe-IT

> Connect your Snipe-IT asset management instance so Serval workflows and Catalyst can look up, check out, and manage your hardware, licenses, and users.

## About Snipe-IT

[Snipe-IT](https://snipeitapp.com) 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](https://snipe-it.readme.io/docs) 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

| Capability                                       | Description                                                                                                                                                                           |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hardware assets                                  | List, create, update, and delete assets; look up by asset tag or serial number; check assets out and in; restore deleted assets; manage asset files; see licenses linked to an asset. |
| Asset audits                                     | Record asset audits and list assets with audits due or overdue.                                                                                                                       |
| Users                                            | Manage users, restore deleted users, and view a user's assigned assets, accessories, licenses, and accepted EULAs.                                                                    |
| Licenses and seats                               | Full license management, plus listing license seats and updating individual seat assignments.                                                                                         |
| Accessories, consumables, and components         | Create, update, and delete all three; check accessories and components out and in; check out consumables; and see who or what each item is checked out to.                            |
| Models, categories, manufacturers, and suppliers | Manage the asset catalog, including model files.                                                                                                                                      |
| Status labels                                    | Manage status labels and list the assets carrying each label.                                                                                                                         |
| Companies, locations, departments, and groups    | Manage the organizational structure records used for asset assignment and multi-company setups.                                                                                       |
| Custom fields and fieldsets                      | Manage custom fields and fieldsets, including associating and disassociating fields with fieldsets.                                                                                   |
| Maintenance, reports, and backups                | Manage asset maintenance records, pull the activity report, and list or download settings backups.                                                                                    |

Anything defined in the [Snipe-IT API](https://snipe-it.readme.io/reference/api-overview) 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](https://snipe-it.readme.io/reference/authenticating-with-the-api).

<Steps>
  <Step title="Log in to your Snipe-IT instance">
    For example, [https://your-company.snipe-it.io](https://your-company.snipe-it.io), or your self-hosted domain.
  </Step>

  <Step title="Open Manage API Keys">
    Click your account dropdown in the top-right corner and select **Manage API Keys**.
  </Step>

  <Step title="Create a token">
    Click **Create New Token** and give it a descriptive name (for example, "Serval Integration").
  </Step>

  <Step title="Copy the key immediately">
    Keep it somewhere safe until you have pasted it into Serval.
  </Step>
</Steps>

<Warning>
  Snipe-IT shows the API key only once. If you lose it, you must generate a new one.
</Warning>

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

## Connect in Serval

<Steps>
  <Step title="Open the Snipe-IT connect form">
    In Serval, open the Snipe-IT integration and start a new connection.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Enter your API Key (required)">
    Paste the key you copied from Snipe-IT. The field hides the value as you type.
  </Step>

  <Step title="Save the connection">
    Saving the form does not test the key against Snipe-IT. Verification happens right afterward via the health checks below.
  </Step>
</Steps>

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

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

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

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="The connect form does not test your API key">
    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.
  </Accordion>

  <Accordion title="Connecting fails with a generic error message">
    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.
  </Accordion>

  <Accordion title="API key permissions mirror the creating user">
    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.
  </Accordion>

  <Accordion title="Updating the connection keeps existing values unless you change them">
    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.
  </Accordion>

  <Accordion title="Large inventories come back one page at a time">
    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.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Snipe-IT integration.