Quickstart

By the end of this page your agent has an account at a third-party app — connected (one you already own) or registered (a new one) — and a browser session logged into it. You will not create an email identity first. Sente provisions the backing address for you. Everything runs against https://api.sente.run/v1.

Get an API key

Sign in at app.sente.run. The first sign-in creates your organization and puts you on the free tier — no card.On the API keys page, create a key and export it:

export SENTE_API_TOKEN=sk_sente_...

The API accepts it as Authorization: Bearer <key>. One key authenticates the whole organization — treat it like a production secret.

Install a client

npm install -g @sente-labs/cli   # Node 18+
sente login                      # browser sign-in; stores the key in ~/.sente/credentials

npm install @sente-labs/sdk

pip install sente-sdk           # the import is `sente`

sente login opens a browser and mints a key for you, so you can skip step 1. In CI, set SENTE_API_TOKEN instead — it always wins over the stored file.

Connect an account you already own

You supply the username and password once. Sente logs in with a real browser, vaults the credentials write-only, and keeps the account re-loginable. No identityId — the backing email address is provisioned from the app’s hostname.

sente connect https://app.example.com/login \
  --username "ops@yourcompany.com" \
  --password "$APP_PASSWORD"
# blocks until the run settles, printing status lines to stderr
# → Account ready.
#     registration: reg_...

import { Sente } from "@sente-labs/sdk";

const sente = new Sente({ apiKey: process.env.SENTE_API_TOKEN! });

const { connection, run } = await sente.connections.connect({
  appUrl: "https://app.example.com/login",
  credentials: {
    username: "ops@yourcompany.com",
    password: process.env.APP_PASSWORD!,
  },
});
console.log(connection.id, run.id); // reg_... run_...

import os
from sente import Sente

sente = Sente(api_key=os.environ["SENTE_API_TOKEN"])

connection, run = sente.connections.connect(
    app_url="https://app.example.com/login",
    username="ops@yourcompany.com",
    password=os.environ["APP_PASSWORD"],
)
print(connection.id, run.id)  # reg_... run_...

Registering a new account is the same shape — sente register <appUrl> / registrations.register({ appUrl }) — and is only for apps whose terms permit it. Add --confirm-before-submit / confirmBeforeSubmit: true so a human clicks the final submit and accepts the app’s terms. See Register.

SSO-only accounts cannot be connected. If the account signs in only through Google/Okta SSO or a passkey, there is no username and password to vault. Same for accounts whose second factor is SMS — see the block handling in the next step.

Wait for the run, and handle a block

Connecting starts a run: one browser job. It ends completed or failed, or stops at blocked — meaning a human step is required. Nothing is worked around; the run holds for 10 minutes with an interactive live view, then fails with BLOCKED_TIMEOUT.

# `sente connect` already waited. If it printed a block, open the live view it gave you,
# do the step yourself, then:
sente run resume <runId>

# Or watch for blocks across every account and get a desktop notification:
sente watch

const settled = await sente.runs.waitForRun(run.id); // timeout in MILLISECONDS, default 180000

if (settled.status === "blocked") {
  console.log("needs a human:", settled.error?.code, settled.liveViewUrl);
  // ...a person completes the step at liveViewUrl, then:
  await sente.runs.resume(settled.id);
  await sente.runs.waitForRun(settled.id);
} else if (settled.status === "failed") {
  throw new Error(`connect failed: ${settled.error?.code}`);
}

settled = sente.runs.wait_for_run(run.id)  # timeout in SECONDS, default 180

if settled.status == "blocked":
    print("needs a human:", settled.error["code"], settled.live_view_url)
    # ...a person completes the step at live_view_url, then:
    sente.runs.resume(settled.id)
    sente.runs.wait_for_run(settled.id)
elif settled.status == "failed":
    raise RuntimeError(f"connect failed: {settled.error['code']}")

waitForRun takes milliseconds in TypeScript and seconds in Python. It returns the last-polled run on timeout rather than throwing — always check status.

Email verification is the one step you never handle: every inbound email to the account’s address is classified on arrival, and the run injects the code or link itself. See Verification codes.

Use the logged-in session

getSession hands back a remote browser already signed in, as a CDP URL. If the login went stale, Sente re-logs in first (vaulted credentials plus a fresh code from the account’s inbox) and sets healed: true — a cold call can take a minute.

CDP_URL=$(sente session open <registrationId>)   # only the CDP url goes to stdout
# ...drive it with connectOverCDP / puppeteer.connect...
sente session close <registrationId>

import { chromium } from "playwright";

const s = await sente.registrations.getSession(connection.id);
const browser = await chromium.connectOverCDP(s.cdpUrl);
const page = browser.contexts()[0].pages()[0];
await page.goto("https://app.example.com/settings");
// ...
await sente.registrations.closeSession(connection.id);

from playwright.sync_api import sync_playwright

s = sente.registrations.get_session(connection.id)
with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(s["cdpUrl"])
    page = browser.contexts[0].pages[0]
    page.goto("https://app.example.com/settings")
    # ...
sente.registrations.close_session(connection.id)

One live session per identity, and open sessions bill per minute — always close them. To use your own browser stack instead, export a portable Playwright storageState: sente session export <registrationId> / registrations.exportSession(id). See Sessions.

What just happened

You never created an email identity, but one exists. When identityId is omitted, Sente auto-provisions the backing identity from the app’s hostname: app.example.com becomes app-example@sente.run, and a taken address gets a short random suffix (app-example-x7k2@sente.run). That address is a real mailbox — it receives the app’s verification emails, notifications, and password resets, and the run reads them.

sente identity list   # the address Sente provisioned for you

Two consequences worth knowing:

The identity counts against your plan’s identity cap. If auto-provisioning would exceed it, the call returns 429 IDENTITY_LIMIT_EXCEEDED — pass an existing identityId to reuse an address across several apps, or upgrade.
If the connect or register itself then fails, the auto-created identity is rolled back, so a failed attempt does not eat the cap.

Pass identityId explicitly when you want several accounts to share one mailbox, or when the address matters (it appears in the app’s UI as the account’s email).

When it doesn’t work

What you get	What it means	What to do
`429 IDENTITY_LIMIT_EXCEEDED`	Auto-provisioning would exceed your plan’s identity cap	Reuse an address with `identityId`, or upgrade
`429 RUN_LIMIT_EXCEEDED`	Daily or monthly run cap for the org	Wait, or upgrade — see Limits
`409 ALREADY_REGISTERED`	You called connect on an origin where Sente already created an account	Use that registration id
`409 ALREADY_CONNECTED`	You called register on an origin already connected for this identity	Use that connection id
`400 BAD_TOTP_SEED`	`totpSeed` isn’t valid base32 or an `otpauth://` URI	Re-copy the secret from the app’s “can’t scan?” link
Run `blocked` `MFA_REQUIRED`	An email or SMS code went to the owner’s inbox, not Sente’s	Enter it in the live view, then resume
Run `blocked` `CAPTCHA_REQUIRED`	The site served a CAPTCHA	A person solves it in the live view, then resume
Run `blocked` `PHONE_REQUIRED`	The site wants a phone number or SMS code	A person handles it in the live view, then resume
Run `failed` `LOGIN_UNCONFIRMED`	The agent could not confirm it ended up signed in	Check the credentials, then retry
Run `failed` `VERIFICATION_TIMEOUT`	No usable verification email arrived in time	Retry; check the app actually sent to the identity’s address
Run `failed` `BLOCKED_TIMEOUT`	Nobody cleared the block within the 10-minute hold	Retry, and subscribe to `run.blocked` so you hear about it

Full lists: Run statuses and error codes · Human takeover.

Let a coding agent do the setup for you

Paste this into Claude Code, Cursor, or any coding agent that can read a URL:

Read https://sente.run/skill.md and set yourself up with an email address

The agent installs the CLI, runs sente login, provisions an identity, writes the key to .env, and wires send/receive into your codebase. One step still needs you: sente login opens a browser for you to sign in.

Next steps

Accounts — the account object, created vs connected, and how the identity relates to it.
Verification codes — waitForOtp and sente wait --otp for the signups you drive yourself.
Webhooks — get pushed run.blocked, run.completed, and run.failed instead of polling.

Get started

Accounts

Runs

Email

Events & audit

Trust

What just happened

When it doesn’t work

Next steps

​What just happened

​When it doesn’t work

​Next steps

What just happened

When it doesn’t work

Next steps