MSP seat client guide

01How seats work

An MSP (managed service provider) creates organizations for its clients and invites their staff as seats. A seat holder never creates a password. The invite email gives them two things: their Organization ID (for example ACME_CORP) and one activation code per product they were given, such as DNET-A7K2-9FQ4-MMX4-P3ZR. Your client turns those into two credentials, each accepted in a different place.

02Activating a device

Activate

const res = await fetch(`${BASE_URL}/msp/v1/license/activate`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    organizationId: "ACME_CORP",
    code: "DNET-A7K2-9FQ4-MMX4-P3ZR",
    installId,                 // crypto.randomUUID(), stored on first run
    extensionVersion: "1.0.3",
  }),
});
const license = await res.json();

{
  "status": "activated",
  "licenseToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "tokenExpiresAt": "2026-10-09T09:30:00.000Z",
  "plan": "msp",
  "licenseExpiresAt": null
}

Daily validate

const res = await fetch(`${BASE_URL}/msp/v1/license/validate`, {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: `Bearer ${licenseToken}` },
  body: JSON.stringify({ installId, extensionVersion: "1.0.4" }),
});
// Same shape as activate, with "status": "validated". Store the new licenseToken.

Deactivate and verify locally

03Getting a session

The license token is never accepted for workflow calls. Exchange it once for a normal session, then keep that session alive the same way every other Datacove client does.

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 1800
}

async function getAccessToken() {
  const s = await storage.get("session");
  if (s && Date.now() < s.expiresAt - 60_000) return s.accessToken;
  if (s) {
    const res = await fetch(`${BASE_URL}/auth/v1/refresh`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ refreshToken: s.refreshToken }),
    });
    if (res.ok) return save(await res.json());
  }
  // No session yet, or refresh was rejected: exchange the license again.
  const res = await fetch(`${BASE_URL}/msp/v1/license/session`, {
    method: "POST",
    headers: { Authorization: `Bearer ${await storage.get("licenseToken")}` },
  });
  if (!res.ok) throw new LicenseError((await res.json()).error?.message); // license_invalid
  return save(await res.json());
}

async function save({ accessToken, refreshToken, expiresIn }) {
  await storage.set("session", { accessToken, refreshToken, expiresAt: Date.now() + expiresIn * 1000 });
  return accessToken;
}

Run renewals one at a time: if several calls need a new token at once, they should share one refresh. A refresh token that has already been replaced and is used again ends the session as a precaution. The Android guide's session section lists the 401 codes you may see (SESSION_EVICTED, SESSION_REVOKED, TOKEN_REUSED, REFRESH_INVALID).

04Client state rules

All devices one person activates share the same seat user, so runs from their browser extension and their phone appear together. Your client never sends its own identity; the server works it out from the activation.

05Running workflows

const res = await fetch(`${BASE_URL}/workflows/v1/execute`, {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: `Bearer ${await getAccessToken()}` },
  body: JSON.stringify({ id: "wf-sec-001", input: { url: "https://login-verify-account.example" } }),
});
const result = await res.json(); // instant workflow: this is the analysis

Sending files

Attach files to the execute call itself. Seat clients can't use /media/v1/upload, which needs an app API key. Send id as a plain text field, every non-file input in one text field named input as a JSON string ({} if there are none), and each file as a part named after its input key. Don't set Content-Type yourself; let the HTTP client add the multipart boundary.

const form = new FormData();
form.append("id", "wf-sec-008");
form.append("input", JSON.stringify({}));              // non-file inputs, none here
form.append("document", fileBlob, "contract.pdf");   // part name = the input's key

const res = await fetch(`${BASE_URL}/workflows/v1/execute`, {
  method: "POST",
  headers: { Authorization: `Bearer ${await getAccessToken()}` },
  body: form,
});
const { eventId } = await res.json();                  // report workflow: see the next section

06Report results

Report history, sharing and deletion aren't available to seat sessions. Keep your own list of eventIds if your client shows past results.

07Workflow reference

The security workflows MSP plans draw from, as currently defined. Your MSP's plan decides which ones a seat can run. Input keys and file limits can change; re-check this table when you update your client.

08Errors

Every error uses the same envelope. On license routes, error.message is a stable code such as invalid_code; branch on it.

{
  "statusCode": 401,
  "timestamp": "2026-10-02T09:30:00.000Z",
  "path": "/api/msp/v1/license/activate",
  "error": { "statusCode": 401, "error": "Unauthorized", "message": "invalid_code" }
}