Which Linea client to use, and which key goes where
The TypeScript SDK has a server client, an environment client for production starts, an end-user client for browsers, and a webhook verifier. Each one takes a different credential.
- SDK
- Builder

The Linea TypeScript SDK is not one client. It is four entry points, and each one is built for a different place your code runs and a different credential it is allowed to hold. Picking the right one is mostly a question of where the code lives.
This post sorts them out using the SDK's own documentation, and ends with the limits worth knowing before you build on it.
Four entry points
| Entry point | Runs where | Credential | What it is for |
|---|---|---|---|
| `Linea` | Your server, a script, a CI job | A workspace API key | Build, run and monitor workflows |
| `LineaEnvironmentClient` | Your server | An environment key | Start production runs |
| `@linealabs/sdk/user` | Browser, edge, native | A verified end user session | Start and follow runs for one user |
| `@linealabs/sdk/webhooks` | Your server | Webhook secret | Verify webhook deliveries |
The first rule follows from the table. A workspace API key is a bearer credential for the whole workspace, so it never leaves trusted server code. The end-user entry point exists so that browsers and devices never need one. It does not accept an API key at all.
The server client
Linea takes a workspace API key and groups its methods by resource: workflows, executions, signals, regressions and audit events.
TypeScript
import { Linea } from "@linealabs/sdk"
const linea = new Linea({ apiKey: process.env.LINEA_API_KEY! })
const execution = await linea.workflows.run(workflow.id, {
input: { ticketId: "T-123" },
})
const { execution: finished, steps } = await linea.executions.wait(execution.id)
console.log(finished.status, steps.length)run starts the version bound to the dev environment. wait polls every second until the execution succeeds, fails or is cancelled, and gives up with a timeout error after five minutes. You can change both with intervalMs and timeoutMs.
The same client can also create workflows and save drafts and versions, because workflows have a write scope. What it cannot do is publish. Publishing a version and binding it to an environment need a signed-in workspace admin, so those two steps happen in the dashboard. That split is deliberate: an API key can prepare a graph, but a person releases it.
Keys are scoped, and they expire
An API key is created in the dashboard under Settings, then API Keys, by an admin session. A key cannot create other keys, so a leaked key cannot mint more of itself. The raw key is shown once.
Each key carries an explicit list of scopes and a lifetime of 1 to 365 days. Grant only what the integration calls:
workflows:readandworkflows:writefor managing workflowsexecutions:startfor starting a runexecutions:readfor reading executionssignals:readandsignals:writefor signals
A key also stops working when the admin who created it leaves the workspace or loses the admin role. Plan for that: a key tied to one person's role is a key that can quietly stop.
Running in production
Production starts use the environment client with an environment key from the environment's Backend keys tab. The workflow binding must also allow backend starts, so a key alone is not enough.
TypeScript
import { LineaEnvironmentClient, environmentKey } from "@linealabs/sdk"
const production = new LineaEnvironmentClient({
environmentId: "env_123",
environmentKey: environmentKey(process.env.LINEA_ENVIRONMENT_KEY!),
})
const started = await production.startExecution({
workflowId: "wf_123",
externalSubjectId: "user_123",
input: { ticketId: "T-123" },
})
const result = await production.waitForExecution(started.id)
console.log(result.status, result.output)Notice externalSubjectId. It names the person the run is for, which is what memory is keyed on later.
Browsers and devices
The end-user client is the one that is safe to ship. It starts an authorization, completes it after the redirect, and keeps only an opaque session bound to a proof key. Browsers keep that state in IndexedDB, edge runtimes keep it in memory, and React Native apps supply their own secure storage.
From there it can create a conversation, start an execution, refresh it, and stream events. Event notifications are hints, not state. After a reconnect the client emits a reconciled event, and you should replace your local snapshot with the authoritative list before handling later events.
Limits to know about
Read these before you build.
- No automatic retries. A failed request is never retried for you. Retrying a call like
workflows.runcan start a duplicate execution, so that decision is left to your code. - Reads are capped for one workflow. Listing executions for a single workflow returns at most 50 rows, with no pagination. The general execution list does paginate with a cursor.
- Costs arrive as strings.
costMicrosis a 64-bit integer, so it comes over JSON as a decimal string. Convert it before doing arithmetic. - Two error types. Requests throw an API error when the server answered with a failure, and a network error when the request never arrived. Handle both.
Start from where your code runs. A server script uses Linea, a production backend uses the environment client, and anything that ships to a user uses the end-user entry point. The credential follows from that choice, and so do most of the mistakes you avoid.


