Appearance

API ​

ViMi Labs provides API access for external applications that need to connect to a lab programmatically.

This page explains the basic setup:

  • how to create API access in ViMi
  • how authentication works
  • how lab scope works
  • how an application can make its first request

Detailed endpoint documentation will be added separately.

Create API Access ​

To connect an external application, first create an API key in ViMi Labs.

When creating the key:

  • give it a label so you can identify it later
  • choose whether the API key should be:
    • open scope, or
    • scoped to your active lab

After creation, ViMi shows a bearer token once.

This is the token your application should store and use for requests.

Important:

  • the token is shown only once
  • if you lose the token, you must regenerate it
  • regenerating the token immediately invalidates the old one

Store the Token ​

The external application should store the token securely.

A typical setup looks like this:

env
VIMI_API_TOKEN=...
VIMI_LAB=...

Where:

  • VIMI_API_TOKEN is the bearer token generated by ViMi
  • VIMI_LAB is the ViMi lab_code

Authentication ​

ViMi expects the generated token to be sent as a bearer token.

Send it in the request headers:

http
Authorization: Bearer {VIMI_API_TOKEN}
Content-Type: application/json

All API communication should use JSON.

How Lab Scope Works ​

ViMi API access is always tied to a user and a lab context.

There are two key modes:

  • open scope
  • single-lab scope

Open scope means:

  • the API key can be used for any lab the user currently has access to

Single-lab scope means:

  • the API key can only be used for its configured lab

In both cases, ViMi still checks whether the user currently belongs to the requested lab.

If the user loses access to a lab, the external application also loses access to that lab.

Lab-Scoped Routes ​

User-related API routes are reserved under:

text
api/v1/user/...

Lab discovery is available under:

text
api/v1/labs

Lab-specific operations are reserved under:

text
api/v1/lab/{lab_code}/...

The lab_code is the canonical lab identifier for API requests.

First Request ​

If the application needs to confirm which labs are accessible, it should start with:

http
GET /api/v1/labs
Authorization: Bearer {VIMI_API_TOKEN}
Content-Type: application/json

This returns the labs the API key is currently allowed to access.

If the integration already knows the correct lab, it can use that lab_code for future lab-scoped requests.

What ViMi Checks ​

For each authenticated request, ViMi will:

  1. decode the bearer token
  2. find the matching API key record
  3. verify that the token is valid
  4. verify that the key is not expired
  5. verify that the request is associated with the correct user
  6. verify that the requested lab is still accessible
  7. enforce key scope if the key is lab-scoped

If any of these checks fail, the request is rejected.

Regeneration and Expiration ​

API keys support secret regeneration and inactivity expiration.

  • regenerating a key creates a new token
  • the old token stops working immediately
  • API keys expire after 90 days of inactivity

If a key expires or a token is lost, generate a new token in ViMi Labs before reconnecting the external application.