How do I use the REST API? Creating API receivers and API keys

The REST API connects Inventory ONE to your own systems, for example an ERP, an HR system or a fleet management system. Your system then reads and maintains inventory, storages, locations and receivers directly through the interface instead of you entering the data by hand. Access is controlled by API keys. Every API key belongs to an API receiver, which represents your connected system in Inventory ONE.

Prerequisites

• The REST API is enabled for your account. It is an optional add-on in the Basis 500 and Pro 4.000 plans and included in the Big 10.000 plan (see Plans and pricing). Without it, the API receivers tab is missing from user management. In that case, contact our support and we will enable the interface for your account.
• You have the technical documentation of the interface (OpenAPI specification). You receive it from our support; it describes all endpoints, fields and error messages for your developers.
• Your role may manage API receivers and API keys. Administrators may do so by default. For custom roles you need the permissions See, Create, Edit and Delete for the receiver type API receivers in the Receivers area, plus the permissions See API keys, Create API keys and Delete API keys in the API keys area (see How do I create custom user roles?).

What is an API receiver?

An API receiver is a technical receiver without a login. It stands for a connected system, for example "ERP" or "HR system". The API keys your system uses to authenticate at the interface belong to it. Create a separate API receiver for every connected system. That way you can later see which system has which keys and disconnect one system without affecting the others. Inventory cannot be assigned to an API receiver; it only serves the connection. If business units are active for your account, you assign the API receiver to a business unit when creating it.

Creating an API receiver

1. Open Settings → Users and switch to the API receivers tab.
2. Click Create new API receiver.
3. Enter a name, for example the name of the system you want to connect. If business units are active, also select the business unit.
4. Click Save.

The overview lists all API receivers with their name and business unit. Clicking a row opens the detail page. There you can rename the API receiver via Edit and manage its API keys. If you no longer need a connected system, deactivate its API keys (see below); the API receiver itself cannot be deleted in the application.

Creating an API key

1. Open the detail page of the API receiver. The API keys section lists all keys created so far.
2. Click Create new API key.
3. Give the key a name, for example "Production" or "Test". The name appears in the table later.
4. Tick Write permission if your system should create, change or delete data. Without the tick the key may only read (see below).
5. Optionally choose an expiration date. After that day the interface no longer accepts the key.
6. Click Save.

Inventory ONE shows you the new key exactly once in the API key created dialog. Copy it now via Copy and store it securely in your system. For security reasons you cannot retrieve the full key again later; the table only shows its beginning. If you lose the key, simply create a new one and deactivate the old one.

For every key, the API keys table shows the name, the beginning of the key, whether it has write permission, the expiration date and the status Active or Deleted.

Read or write permission

API keys are not tied to a user but receive their permissions through a dedicated role (see What roles are there?):

• Without write permission the key works with the predefined role API access (read-only). It may read all data but cannot create, change, delete or book anything. The interface answers writing calls with "No permission".
• With write permission the key works like an administrator and may create, change and delete data.

You find both roles in role management under Settings → Roles, provided it is enabled for your account. You can adjust their permissions there, for example restrict the receiver permissions to certain receiver types; the role API access (read-only) cannot be assigned to a user or used as a template for custom roles, though. Changes to these roles take effect immediately for all API keys that work with them.

Give a key only as many permissions as your system really needs. A system that only evaluates stock levels gets by with a key without write permission. Create a separate key for every system and purpose and set an expiration date. Then you can end individual accesses selectively without affecting the others.

Deactivating an API key

If you no longer need a key or it has fallen into the wrong hands, deactivate it:

1. Open the detail page of the API receiver and select the key's row in the API keys table.
2. Click Deactivate and confirm the prompt.

Afterwards this key no longer grants access through the interface. Deactivation cannot be undone; the key stays visible in the table with the status Deleted. If your system still needs access, create a new key and replace it there.

How your system accesses the interface

The interface is available at https://app.inventory-one.com/api/v2 (for mein_werkzeugkoffer: https://app.meinwerkzeugkoffer.de/api/v2). Your system sends the API key with every call in the HTTP header X-ONE-API-KEY. Data is sent and received as JSON. An example that fetches all employees:

curl -H "X-ONE-API-KEY: YOUR-API-KEY" "https://app.inventory-one.com/api/v2/receivers?type=employee"

If the key is missing, expired or deactivated, the interface answers with status 401. If the key lacks the permission for the action, it answers with 403. If a request violates a rule of the application, for example a duplicate name, it answers with 422 and lists the validation messages you also know from the application. Which fields each endpoint expects and returns is described in the OpenAPI specification.

What can your system do through the interface?

The interface covers the most important data of Inventory ONE. The same rules apply as in the application, for example required fields, unique names and QR codes that are already in use.

• Inventory items: list, read individually, create, edit and delete; create, change and delete reservations; upload documents and images; read inspection results.
• Quantity inventory and consumables: list, read, create, edit and delete.
• Sets: list, read, create, edit and delete.
• Storages and locations: list, read, create, edit and delete.
• Receivers: list (filterable by type), read, create, edit, archive, restore and delete. This applies to employees, external persons, subcontractors, rooms, projects, construction sites, students, school classes, vehicles and API receivers. Name, location, QR codes and archive status can be changed; the type of a receiver cannot be changed. Users remain tied to their login: they are still created and deleted in the application, and through the interface they can only be listed, archived and restored.

A typical use is synchronising receivers: your HR system creates new employees as receivers, renames them when something changes and archives them when they leave. Your fleet management system keeps the vehicles up to date. The same safeguards apply as in the application: duplicate names within a receiver type and QR codes already in use are rejected, and receivers with assigned inventory can be neither archived nor deleted. If you have restricted the receiver permissions of the role Administrator or API access (read-only) to certain receiver types in role management, a key with that role only sees and changes those types; the interface answers requests for other types with "No permission".

Security notes

• Treat API keys like passwords. Do not share them by e-mail or chat and store them only in your connected system.
• Use keys without write permission wherever reading is enough.
• Set an expiration date and renew keys regularly.
• Deactivate a key immediately if you suspect it has fallen into the wrong hands, and create a new one.