Skip to main content

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

Anything defined in the Firstbase API can be accessed through Serval.

​
Get your credentials

You need a Firstbase API token created by an Admin user in the Firstbase admin app.
1

Sign in to Firstbase as an Admin

Go to app.firstbasehq.com and sign in with an Admin account. Only Admin users can create API tokens.
2

Open the Firstbase API settings

Open the Settings menu in the top navigation bar and select Firstbase API.
3

Create a token

Create a new token and give it a recognizable name, for example “Serval Integration”.
4

Copy the token value

Copy the token - you will paste it into Serval in the next section.
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.

​
Connect in Serval

1

Open Firstbase in the Serval integrations catalog

Find Firstbase in the integrations catalog and start the connection.
2

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

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

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

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

​
Gotchas and troubleshooting

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.”
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.
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.
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.
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.
Endpoint coverage tracks the Firstbase public API specification and may change as that specification evolves.
Need help? Contact support@serval.com for assistance with your Firstbase integration.