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

# Firstbase

> Connect Firstbase to Serval with an API key so workflows can manage device orders, inventory, returns, ITAD, and SCIM user provisioning.

## About Firstbase

Firstbase is an IT equipment lifecycle platform covering device ordering and catalog, inventory tracking, shipments, returns and replacements, IT asset disposition (ITAD), and SCIM user provisioning for onboarding and offboarding. Serval connects to Firstbase with a single API key and gives your workflows full access to the Firstbase public API, including its SCIM provisioning endpoints. The integration is currently marked **Beta** in the Serval apps catalog.

**Authentication:** API key

**Data sync:** On-demand only. Nothing is imported from Firstbase on a schedule - workflows read and write Firstbase data live, and three health checks run automatically right after you connect to confirm the key works.

## What the Firstbase integration enables

| Capability                     | Description                                                                                                                                                                                      |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| SCIM user provisioning         | List, look up, create, update, and remove users, plus bulk operations and CSV bulk upload. Removing a user is a soft delete that starts the Firstbase offboarding process.                       |
| Inventory and asset tracking   | List all inventory and get asset details with rich filters (person, warehouse, deployment status, SKU, search text, date ranges); add and remove inventory tags; manage inventory levels.        |
| Equipment orders               | List and create orders, look up a specific order, and approve or decline orders awaiting approval. Orders can ship to a person or an office.                                                     |
| Returns and replacements       | Create and track return orders with return-kit shipping, office returns, and optional address confirmation; create replacements that pair a return with a new equipment order.                   |
| Shipments and shipment notices | List shipments; create and track inbound shipment notices from a supplier or office; create inventory orders that send equipment to a warehouse.                                                 |
| Catalog and packages           | Read your organization's catalog SKUs and equipment packages.                                                                                                                                    |
| ITAD (IT asset disposition)    | List eligible ITAD assets, create disposition requests (automatically grouped into one request per warehouse), and track request status including resale values and certificates of destruction. |
| New joiners and people emails  | List new joiners with stats and filters, send new-joiner reminder emails, and trigger admin emails per person (resend activation, resend offboarding, send a platform invite).                   |
| Logistics reference data       | Read the warehouses, regions, and offices configured for your organization.                                                                                                                      |

Anything defined in the [Firstbase API](https://apipub.firstbasehq.com/swagger-ui/index.html) can be accessed through Serval.

## Get your credentials

You need a Firstbase API token created by an **Admin** user in the [Firstbase admin app](https://app.firstbasehq.com/).

<Steps>
  <Step title="Sign in to Firstbase as an Admin">
    Go to [app.firstbasehq.com](https://app.firstbasehq.com/) and sign in with an Admin account. Only Admin users can create API tokens.
  </Step>

  <Step title="Open the Firstbase API settings">
    Open the **Settings** menu in the top navigation bar and select **Firstbase API**.
  </Step>

  <Step title="Create a token">
    Create a new token and give it a recognizable name, for example "Serval Integration".
  </Step>

  <Step title="Copy the token value">
    Copy the token - you will paste it into Serval in the next section.
  </Step>
</Steps>

<Tip>
  To rotate the key later, create a new token in the Firstbase app, enter it in Serval's connection settings (use the pencil icon next to the masked key), and then delete the old token in Firstbase.
</Tip>

## Connect in Serval

<Steps>
  <Step title="Open Firstbase in the Serval apps catalog">
    Find **Firstbase** in the apps catalog (it carries a Beta badge) and start the connection.
  </Step>

  <Step title="Paste your API key">
    Fill in the one field on the form, **API Key** (required, shown as "API Key \*"). The helper text reads: "Your Firstbase API key. You can generate one from your Firstbase account settings." The input is masked as you type, and the form will not submit while the field is empty.
  </Step>

  <Step title="Save the connection">
    Serval stores the key and pins the connection to a single instance named "Firstbase". If saving fails, you will see "Failed to connect service" or "Failed to install integration" - double-check that you pasted the complete token.
  </Step>

  <Step title="Let the health checks run">
    Immediately after a successful connect, Serval automatically runs the integration's three health checks so your key is verified right away.
  </Step>
</Steps>

<Note>
  When you later open the connection settings, the saved key is shown masked as bullet characters plus its last 4 characters, and the masked value is read-only. You never need to re-enter the existing key: to rotate it, click the pencil icon (or the **Replace** button on the reconnect form), paste the full new key into the "Enter new value" box, and save. If you clear the box and save without entering a new key, the existing key is kept. After a successful update Serval re-runs the health checks automatically; if the update fails, you will see "Failed to update configuration" on the settings page or "Failed to update integration" on the reconnect form.
</Note>

## Verifying the connection

Serval runs three health checks for Firstbase - automatically after you connect or update the key, and on demand from the connection's health panel using the **Run** button. Each one makes a minimal read request to prove the key works:

* **Test Firstbase List Packages** - reads a single entry from your equipment packages list. Success: "Successfully connected to Firstbase and retrieved packages list". Failure: "Failed to connect to Firstbase or list packages. Please check your API key and permissions."
* **Test Firstbase List Inventory** - reads a single entry from your inventory. Success: "Successfully connected to Firstbase and retrieved inventory list". Failure: "Failed to connect to Firstbase or list inventory. Please check your API key and permissions."
* **Test Firstbase List Users (SCIM)** - reads a single user through Firstbase's SCIM provisioning interface. Success: "Successfully connected to Firstbase and retrieved users via SCIM". Failure: "Failed to connect to Firstbase or list users. Please check your API key and permissions."

<Tip>
  If the packages and inventory checks pass but the SCIM users check fails, your key can read equipment data but not people data. Recreate the token while signed in as a Firstbase Admin and reconnect.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Health checks fail right after connecting">
    The most common causes are an incomplete paste of the token or a token created by a non-Admin user. Create a fresh token as an Admin under Settings > Firstbase API, paste the complete value into Serval, save, and re-run the health checks. Failure messages all end with "Please check your API key and permissions."
  </Accordion>

  <Accordion title="Firstbase data does not appear in Serval automatically">
    This integration has no scheduled sync - nothing is imported from Firstbase in the background, and there are no prebuilt sync workflows. All data access happens live when a workflow runs, so any dashboard or entity built on Firstbase data needs a workflow to fetch it.
  </Accordion>

  <Accordion title="Removing a user starts offboarding, not an instant delete">
    Deleting a user through the SCIM provisioning capability is a soft delete that kicks off the Firstbase offboarding process - the person keeps Firstbase platform access until offboarding completes. Relatedly, the OFFBOARDING return reason cannot be set when creating returns through the API.
  </Accordion>

  <Accordion title="Testing the key outside Serval">
    Firstbase expects the credential in an Authorization header using the "ApiKey" scheme, which Serval applies for you on every request. If your team tests the key manually with another tool, a standard "Bearer" header will be rejected by Firstbase even though the key itself is valid.
  </Accordion>

  <Accordion title="There is no server, region, or subdomain field">
    The connection is always pinned to Firstbase's public API service at apipub.firstbasehq.com, with the instance display name "Firstbase". Your key is only ever sent to that host, and no instance URL needs to be (or can be) configured.
  </Accordion>

  <Accordion title="Beta integration">
    Firstbase appears with a Beta badge in the Serval apps catalog. Endpoint coverage tracks the Firstbase public API specification and may change.
  </Accordion>
</AccordionGroup>

***

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