Agent access

A human owns the lab and never hands over a key: the agent gets its own wallet, the human grants it Contributor, the agent issues its own token.

The most common real-world shape: a researcher created their Lab in the Labs app with an email address — no wallet, no code — and now wants an agent contributing to it. The agent gets its own identity rather than borrowing the human's; the human grants it a role; the agent authenticates itself from then on.

Before you start: you need the two prerequisites — a mol_ consumer credential and a funded Base Sepolia wallet — plus the shared setup block, which defines the config constants and the graphql() / assertOk() helpers every snippet below uses. The complete script at the end of this page carries all of it inline and runs standalone. Unfamiliar with a term used here? See the Glossary.

Who does what:

#	Actor	Action
1	Agent	Generate a wallet and report its address
2	Human	Add that address to the lab as Contributor, flagged as an agent, with an expiry
3	Agent	Self-issue a service token by signing the sign-in message
4	Agent	Upload files; the human sees the result in the app

The human never hands over a private key, a token, or their session. Revoking the agent is one onchain revoke, and it does not touch anything else.

Three addresses are in play here — the human's owner wallet, the agent's own wallet, and the Lab's own OCL account — and they are not interchangeable. If you are unsure which goes in which field, read the three wallets, side by side first.

Step 1: The agent reports its address

With the plugin: run wallet_address. With viem:

import { privateKeyToAccount, generatePrivateKey } from "viem/accounts";

// Generate once, store it as the agent's own secret — never the human's key.
const agentPrivateKey = process.env.AGENT_PRIVATE_KEY ?? generatePrivateKey();
const agentAccount = privateKeyToAccount(agentPrivateKey);
console.log("Agent wallet address:", agentAccount.address);

Give that address to the lab owner. The agent needs no gas for this tutorial — it never sends a transaction, only signs a message. (Persist agentPrivateKey if you generated it, or the next run is a different agent with no role.)

Step 2: The human grants Contributor

In the Labs app, the lab owner adds the agent's address to the lab's members and grants it the Contributor role, setting:

• isAgent = true — informational metadata that marks the member as an agent identity in the members list and UI. It does not change authorisation.

• an expiry — typically the agent's session lifetime. When it lapses the agent loses access until it is re-granted; a permanent grant is possible but not the default you want for an agent.

Members can be invited by wallet address, ENS name or email, and the app sponsors the gas for the grant. Under the hood this is one onchain call on the AccessResolver, which the owner (or an existing Contributor, for Viewer grants) can also make directly:

function grantRole(bytes32 oclId, address account, uint8 role, uint64 expiry, bool isAgent) external;
// role: 2 = ROLE_CONTRIBUTOR, 1 = ROLE_VIEWER

Only the Owner may grant Contributor. Contributors can grant Viewer, but not Contributor. Full capability matrix: Roles & Permissions.

Why Contributor and not Viewer: a Viewer can decrypt and read but cannot write. Uploading files needs Contributor.

Both parties can confirm the grant landed with a public query — no authentication beyond the consumer credential:

const members = await graphql(
  `query ListLabMembers($oclId: String!) {
    listLabMembers(oclId: $oclId) {
      members { walletAddress role isAgent expiry grantedAt }
    }
  }`,
  { oclId },
);
const grant = members.listLabMembers.members.find(
  (m) => m.walletAddress.toLowerCase() === agentAccount.address.toLowerCase(),
);
console.log("Agent role:", grant?.role, "expiry:", grant?.expiry ?? "permanent");

Expect role: "CONTRIBUTOR". isAgent simply echoes the flag the owner set — false there changes nothing about what the agent may do, so do not treat it as a failed grant. expiry is unix seconds as a decimal string, or null for a permanent grant. Expired grants are excluded from this list entirely, so a missing entry after a while means the grant lapsed.

Step 3: The agent self-issues a service token

Identical to Step 1 of Create a lab and upload a public file, signed by the agent's wallet. Fetch the message and redeem it in one go — it embeds a single-use nonce valid for 10 minutes, so an agent that waits for the human's role grant between fetching and signing will hit UNAUTHENTICATED / reason: NONCE_EXPIRED. Poll for the grant first (Step 2), then sign in:

const AGENT_SERVICE_NAME = "research-agent-1";

const signInMessage = await graphql(
  `query GetServiceSignInMessage($walletAddress: String!, $serviceName: String!) {
    getServiceSignInMessage(walletAddress: $walletAddress, serviceName: $serviceName) { message expiresAt }
  }`,
  { walletAddress: agentAccount.address, serviceName: AGENT_SERVICE_NAME },
);

const messageSignature = await agentAccount.signMessage({
  message: signInMessage.getServiceSignInMessage.message,
});

const tokenResult = await graphql(
  `mutation GenerateServiceToken(
    $serviceName: String!
    $walletAddress: String!
    $messageSignature: String!
    $expiresIn: String
  ) {
    generateServiceToken(
      serviceName: $serviceName
      walletAddress: $walletAddress
      messageSignature: $messageSignature
      expiresIn: $expiresIn
    ) {
      token tokenId expiresAt
      error { code message requestId retryable details }
    }
  }`,
  {
    serviceName: AGENT_SERVICE_NAME,
    walletAddress: agentAccount.address,
    messageSignature,
    expiresIn: "30d", // match the role grant's expiry rather than taking the 180d default
  },
);
assertOk(tokenResult.generateServiceToken, "generateServiceToken");
serviceToken = tokenResult.generateServiceToken.token;

Issuance is not gated on holding a role — any wallet can mint a token for itself. The role is what makes the token useful: authorisation is resolved per request from the token's wallet against the lab you name. So a token issued before the grant lands keeps working once it does; you do not need to re-issue it.

Step 4: The agent uploads

From here the agent is an ordinary caller. Run Step 4 of Create a lab and upload a public file with changeBy: agentAccount.address, or Upload an encrypted file for a confidential file — the hasRole branch of the team conditions is exactly what lets the agent decrypt too.

Writes by a Contributor service token are gated per mutation, matching the Privy user path: initiateCreateOrUpdateFile, finishCreateOrUpdateFile, deleteDataRoomFile, updateFileMetadata and moveEntry all accept Contributor. A few surfaces remain Owner-only and an agent Contributor cannot reach them: updateLabNftMetadata, generateLabImageUploadUrl and the legal-agreement mutations.

Retry on UNAUTHORIZED right after the grant. Role state reaches the API through an event indexer, so for a window after grantRole confirms onchain a write still returns UNAUTHORIZED (details.reason is also UNAUTHORIZED — there is no separate NOT_CONTRIBUTOR reason; match on error.code). It is not a permissions problem and re-issuing the token will not help — wait and retry. Usually seconds, but the same indexer has taken minutes on staging, so retry generously:

async function withIndexerLagRetry(
  fn,
  { codes = ["NOT_FOUND"], attempts = 12, baseMs = 2000, capMs = 30000 } = {},
) {
  const laggy = new RegExp(codes.join("|"));
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (err) {
      if (!laggy.test(String(err)) || i === attempts - 1) throw err;
      const delay = Math.min(baseMs * 2 ** i, capMs); // 2s, 4s, 8s, 16s, then 30s
      console.warn(`indexer not caught up (attempt ${i + 1}/${attempts}); retrying in ${delay / 1000}s`);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

// Same helper as in Shared Setup, with the code this step expects.
await withIndexerLagRetry(() => uploadFile(oclId, "./findings.csv"), { codes: ["UNAUTHORIZED"] });

Step 5: Verify from both sides

The agent verifies as in Step 5 of Create a lab and upload a public file — the file is in dataRoom.files with createdBy set to the agent's address:

const verify = await graphql(
  `query Verify($oclId: String!) {
    labWithDataRoomAndFiles(oclId: $oclId) {
      shortname
      dataRoom { files { path accessLevel version createdBy } }
    }
  }`,
  { oclId },
);

The human verifies in the app: the file appears in the lab's data room, attributed to the agent's address, which the members list shows flagged as an agent.

Revoking the agent

One onchain call, and the agent's writes stop:

function revokeRole(bytes32 oclId, address account) external;   // Owner only, for a Contributor

Or let the grant's expiry lapse. Independently, the agent's token can be killed with revokeServiceToken(tokenId) — a token can only revoke or extend its own record, so one agent cannot interfere with another's.

Complete script

The agent's half of the flow, standalone: report the wallet address, wait for the human's grant to appear, self-issue a token, upload, verify. Steps 1 and 2 involve a human, so the script polls for the role rather than assuming it.

Run it with the agent's own key and the oclId of the human's lab — the agent never sees the owner's key.

#!/usr/bin/env node
import { readFileSync } from "node:fs";
import { basename } from "node:path";
import { privateKeyToAccount, generatePrivateKey } from "viem/accounts";

const GRAPHQL_URL = "https://staging.graphql.api.molecule.xyz/graphql";
const LAB_APP_URL = "https://testnet.labs.molecule.xyz";
const AGENT_SERVICE_NAME = "research-agent-1";

const CONSUMER_CREDENTIAL = process.env.CONSUMER_CREDENTIAL;
const OCL_ID = process.env.OCL_ID; // the human's lab
// Persist this, or every run is a different agent with no role.
const AGENT_PRIVATE_KEY = process.env.AGENT_PRIVATE_KEY;

let serviceToken;

async function graphql(query, variables) {
  const headers = { "Content-Type": "application/json", Authorization: CONSUMER_CREDENTIAL };
  if (serviceToken) headers["X-Service-Token"] = serviceToken;
  const res = await fetch(GRAPHQL_URL, {
    method: "POST",
    headers,
    body: JSON.stringify({ query, variables }),
  });
  const { data, errors } = await res.json();
  if (errors) throw new Error(JSON.stringify(errors));
  return data;
}

// `details` arrives as an object (thrown queries), a JSON string (in-band), or
// a doubly-encoded JSON string (in-band today) — parse until it is not a string.
function parseDetails(details) {
  let value = details;
  for (let i = 0; i < 3 && typeof value === "string"; i++) {
    try {
      value = JSON.parse(value);
    } catch {
      break;
    }
  }
  return value && typeof value === "object" ? value : {};
}

function assertOk(result, op) {
  if (result.error) {
    const { code, message, requestId } = result.error;
    const { reason } = parseDetails(result.error.details);
    throw new Error(
      `${op} failed: ${code}${reason ? `/${reason}` : ""}: ${message} (requestId ${requestId})`,
    );
  }
  return result;
}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

// Writes can return UNAUTHORIZED for a few seconds after a role grant confirms
// onchain — the indexer trails the chain. Retry rather than re-issuing the
// token. Same helper as in Shared Setup, which retries NOT_FOUND after a mint.
async function withIndexerLagRetry(
  fn,
  { codes = ["NOT_FOUND"], attempts = 12, baseMs = 2000, capMs = 30000 } = {},
) {
  const laggy = new RegExp(codes.join("|"));
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (err) {
      if (!laggy.test(String(err)) || i === attempts - 1) throw err;
      const delay = Math.min(baseMs * 2 ** i, capMs); // 2s, 4s, 8s, 16s, then 30s
      console.warn(`indexer not caught up (attempt ${i + 1}/${attempts}); retrying in ${delay / 1000}s`);
      await sleep(delay);
    }
  }
}

async function main() {
  const filePath = process.argv[2];
  if (!filePath) throw new Error("Usage: node agent-as-a-lab-contributor.js <file-to-upload>");
  if (!OCL_ID) throw new Error("Set OCL_ID to the lab the human owns");

  // ---- Step 1: the agent's identity ----
  if (!AGENT_PRIVATE_KEY) {
    console.log("No AGENT_PRIVATE_KEY set. Generated one for this run only:");
    console.log("  AGENT_PRIVATE_KEY=" + generatePrivateKey());
    throw new Error("Store that key, grant it Contributor, then re-run.");
  }
  const agentAccount = privateKeyToAccount(AGENT_PRIVATE_KEY);
  console.log("1/5 Agent wallet:", agentAccount.address);
  console.log("    Ask the lab owner to add it as Contributor (isAgent = true).");

  // ---- Step 2: wait for the human's grant (public query, no auth needed) ----
  let grant;
  for (let i = 0; i < 60; i++) {
    const members = await graphql(
      `query ListLabMembers($oclId: String!) {
        listLabMembers(oclId: $oclId) {
          members { walletAddress role isAgent expiry }
        }
      }`,
      { oclId: OCL_ID },
    );
    grant = members.listLabMembers.members.find(
      (m) => m.walletAddress.toLowerCase() === agentAccount.address.toLowerCase(),
    );
    if (grant) break;
    await sleep(5000); // poll for up to 5 minutes
  }
  if (!grant) throw new Error("No role grant found for the agent wallet — ask the owner to add it");
  if (grant.role === "VIEWER") throw new Error("Agent holds VIEWER; uploading needs CONTRIBUTOR");
  console.log("2/5 Role:", grant.role, "isAgent:", grant.isAgent, "expiry:", grant.expiry ?? "permanent");

  // ---- Step 3: the agent self-issues a token ----
  // Only now, after the role poll above returned — the sign-in message holds a
  // single-use nonce that expires 10 minutes after issuance.
  const signInMessage = await graphql(
    `query GetServiceSignInMessage($walletAddress: String!, $serviceName: String!) {
      getServiceSignInMessage(walletAddress: $walletAddress, serviceName: $serviceName) { message expiresAt }
    }`,
    { walletAddress: agentAccount.address, serviceName: AGENT_SERVICE_NAME },
  );
  const messageSignature = await agentAccount.signMessage({
    message: signInMessage.getServiceSignInMessage.message,
  });
  const tokenResult = await graphql(
    `mutation GenerateServiceToken($serviceName: String!, $walletAddress: String!, $messageSignature: String!, $expiresIn: String) {
      generateServiceToken(serviceName: $serviceName, walletAddress: $walletAddress, messageSignature: $messageSignature, expiresIn: $expiresIn) {
        token expiresAt
        error { code message requestId retryable details }
      }
    }`,
    {
      serviceName: AGENT_SERVICE_NAME,
      walletAddress: agentAccount.address,
      messageSignature,
      expiresIn: "30d", // match the role grant rather than taking the 180d default
    },
  );
  assertOk(tokenResult.generateServiceToken, "generateServiceToken");
  serviceToken = tokenResult.generateServiceToken.token;
  console.log("3/5 Token issued, expires", tokenResult.generateServiceToken.expiresAt);

  // ---- Step 4: upload (public; see Upload an encrypted file for the encrypted variant) ----
  // Retried on UNAUTHORIZED: the role grant may not be indexed yet. NOT_FOUND
  // is included for the case where the lab itself was minted moments ago.
  const bytes = readFileSync(filePath);
  const { datasetId } = await withIndexerLagRetry(async () => {
    const initiateResult = await graphql(
      `mutation Initiate($oclId: String!, $contentType: String!, $contentLength: Int!) {
        initiateCreateOrUpdateFile(oclId: $oclId, contentType: $contentType, contentLength: $contentLength) {
          uploadToken uploadUrl method headers { key value }
          error { code message requestId retryable details }
        }
      }`,
      { oclId: OCL_ID, contentType: "application/octet-stream", contentLength: bytes.length },
    );
    assertOk(initiateResult.initiateCreateOrUpdateFile, "initiateCreateOrUpdateFile");
    const { uploadToken, uploadUrl, method, headers } = initiateResult.initiateCreateOrUpdateFile;

    const uploadHeaders = {};
    headers.forEach((h) => (uploadHeaders[h.key] = h.value));
    const putResponse = await fetch(uploadUrl, {
      method: method || "PUT",
      headers: uploadHeaders,
      body: bytes,
    });
    if (!putResponse.ok) throw new Error(`Upload failed: ${putResponse.status}`);

    const finishResult = await graphql(
      `mutation Finish($oclId: String!, $uploadToken: String!, $path: String!, $accessLevel: String!, $changeBy: String!) {
        finishCreateOrUpdateFile(oclId: $oclId, uploadToken: $uploadToken, path: $path, accessLevel: $accessLevel, changeBy: $changeBy) {
          datasetId
          error { code message requestId retryable details }
        }
      }`,
      {
        oclId: OCL_ID,
        uploadToken,
        path: basename(filePath),
        accessLevel: "PUBLIC",
        changeBy: agentAccount.address,
      },
    );
    assertOk(finishResult.finishCreateOrUpdateFile, "finishCreateOrUpdateFile");
    return finishResult.finishCreateOrUpdateFile;
  }, { codes: ["UNAUTHORIZED", "NOT_FOUND"] });
  console.log("4/5 Uploaded — datasetId:", datasetId);

  // ---- Step 5: verify ----
  const verify = await graphql(
    `query Verify($oclId: String!) {
      labWithDataRoomAndFiles(oclId: $oclId) {
        shortname
        dataRoom { files { path accessLevel version createdBy } }
      }
    }`,
    { oclId: OCL_ID },
  );
  const file = verify.labWithDataRoomAndFiles.dataRoom.files.find(
    (f) => f.path.endsWith(basename(filePath)),
  );
  if (!file) throw new Error("File not found in the data room");
  const attributed =
    file.createdBy?.toLowerCase() === agentAccount.address.toLowerCase();
  console.log(
    "5/5 Verified:", file.path, file.accessLevel,
    attributed ? "— attributed to the agent" : `— createdBy: ${file.createdBy}`,
  );
  if (verify.labWithDataRoomAndFiles.shortname) {
    console.log("Human can see it at:", `${LAB_APP_URL}/projects/${verify.labWithDataRoomAndFiles.shortname}`);
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Usage:

# First run — prints a generated agent key, then stops so the owner can grant the role
CONSUMER_CREDENTIAL="mol_…" OCL_ID="0x0101…" node agent-as-a-lab-contributor.js ./findings.csv

# Subsequent runs, once the owner has granted Contributor to that address
AGENT_PRIVATE_KEY="0x..." CONSUMER_CREDENTIAL="mol_…" OCL_ID="0x0101…" \
node agent-as-a-lab-contributor.js ./findings.csv

---

Next

What the agent uploads	Create a lab and upload a public file · Upload an encrypted file
The role model in full	Roles & Permissions
Let the agent run the whole workflow as tool calls	Molecule Skill

Need help?

Ask the team on Discord. Reporting an API error? Include the requestId from the failing response so we can trace it.

Ask on Discord

Page wrong, unclear or missing something? Let us know with Was this helpful? on this page.