API Keys

API Keys are used to allow code to make requests to Instrumental, either for uploading data or retrieving data. To obtain an API Key and use it to access the Instrumental APIs, you will need to work with your Instrumental Solutions Architect. Instrumental will either enable you to provision your own API keys or will provision them for you. Either way, your Instrumental contact can enable you to access the modal shown below so that you can see which keys are active and where they are being used.

Data Streams API Keys modal

Table of Contents

Adding a key

In the API Keys modal, you can click the purple “ADD KEY” button to obtain a new key. It will open a modal showing you your new key. This is the only time Instrumental will display the full key, so make sure to save it.

API Keys look like this:

project-name:key-name:INST:V1:F854DS4QEVIXS4:gZB5txLjMD2+hUjJdzsPI6YOFYkmIQtLebCgLlvS

Treat API keys like passwords, because that’s what they are. Be careful how you share them.

The key consists of several parts separated by colons:

  1. The project name (more specifically, the “slugified” version of it that appears in the URL in the web app) helps ensure that when you are using a key, you are uploading data to the correct project. The project name is optional – the key will still work if you omit it – but if it’s present, it must match the project the key is actually assigned to.
  2. The key name helps identify what the key is used for. For example, if you have multiple factories, you will probably generate a different key for each one, and you can use the key name field to ensure that you send each key to the correct place. Another common use is to identify keys that are used at different stations. The key name field is optional – the key will still work if you omit it, and in fact it is omitted by default when you generate a key in the web app, but you can add it in if it would be helpful. Key names are not currently saved, so you can use any name you want and the key will still work.
  3. INST:V1 indicates that this key uses Instrumental key format version 1.
  4. The next section of 14 random characters is the “public” part of the key – basically the key’s username. This is displayed in the API key modal to identify each key.
  5. The part after the last colon is the “private” part of the key – basically the key’s password.

Keys cannot be reused across different projects, but can be reused across multiple stations within one project. You will need at least one key for your test project and at least one additional key for each “real” project. Ensure that your integration code uses the correct key!

Permissions

Before you click “Add key” you can choose whether the key will have “read” or “write” access (or both). “Read” gives access to the Data Read API and “write” gives access to the Data Streams API and the Image Streams API.

Deactivating a key

To deactivate a key, click the “DEACTIVATE” button next to the key in the API Keys modal. Once this happens, the key can no longer be used to make API requests. You can still see deactivated keys by clicking the “Show deactivated keys” link, but they cannot be reactivated.

Reviewing errors

API requests that authenticate successfully (i.e. they have a valid instrumental-api-key header and are not rate limited) but fail other validation (e.g. the request body is invalid) will be temporarily accessible for debugging through the API key modal:

API Key modal with errors

Clicking “N recent errors” under the key’s inspection count will reveal a list of the most recent failed requests. You can click on each request or response preview to see more details. Up to 100 errors from the last 14 days will be displayed. If you have more than 100 errors in the last 14 days and you need to recover data from them, contact your account manager to see if we can help.

Recovering a key’s project

If you have an API key without the project-name prefix (i.e. it starts with INST:V1) and you need to find out which project it is associated with, you can make a GET request to https://api.instrumental.ai/api/v0/externalData/projectName with the key in an instrumental-api-key header. The response will contain only the project name. For example:

curl -XGET -H 'instrumental-api-key: YOUR_API_KEY' https://api.instrumental.ai/api/v0/externalData/projectName

(Make sure to replace YOUR_API_KEY with your actual API key. You will need the full key, not just the short identifier displayed in the API key modal.)

What’s next?

Return to the Support page to find documentation about the API endpoint you would like to use.