Accounts

The object you work with is an account — your agent’s login at one third-party app. You get one with a single call:

Connect an account you already own (POST /v1/connections), or
Register a new one where the app’s terms permit it (POST /v1/registrations).

Both return the same object plus the run that logs in. Everything else — the credential vault, the logged-in browser session, the mailbox that receives verification codes — hangs off that account. The email address is plumbing. You don’t create one first; omit identityId and Sente provisions the backing identity for you.

One call

sente connect https://app.mailtrap.io/signin \
  --username "ops@yourcompany.com" \
  --password "$MAILTRAP_PASSWORD"
# waits for the run, prints the connection id and status (exit 1 if it did not complete)

sente connections          # → appUrl  status  run:completed  reg_…
sente identity list        # → the address that was provisioned for it

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

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

// No identityId — the backing email identity is provisioned from the app's hostname.
const { connection, run } = await sente.connections.connect({
  appUrl: "https://app.mailtrap.io/signin",
  credentials: { username: "ops@yourcompany.com", password: process.env.MAILTRAP_PASSWORD! },
});

const settled = await sente.runs.waitForRun(run.id);      // timeout is in MILLISECONDS
if (settled.status === "blocked") throw new Error(`needs a human: ${settled.liveViewUrl}`);

// The identity that appeared by itself:
const identity = await sente.identities.get(connection.identityId);
console.log(connection.id, connection.kind, identity.email);
// reg_…  connected  app-mailtrap@sente.run

import os
from sente import Sente

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

# No identity_id — the backing email identity is provisioned from the app's hostname.
connection, run = sente.connections.connect(
    app_url="https://app.mailtrap.io/signin",
    username="ops@yourcompany.com",
    password=os.environ["MAILTRAP_PASSWORD"],
)

settled = sente.runs.wait_for_run(run.id)                 # timeout is in SECONDS
if settled.status == "blocked":
    raise RuntimeError(f"needs a human: {settled.live_view_url}")

identity = sente.identities.get(connection.identity_id)
print(connection.id, connection.kind, identity.email)
# reg_…  connected  app-mailtrap@sente.run

The account

The API returns the same projection everywhere (POST /v1/connections calls it connection, POST /v1/registrations calls it registration — same object, same id space, reg_…):

Field	Meaning
`id`	`reg_…`. The handle for credentials, sessions, re-login, revoke.
`identityId`	The email identity behind it — passed by you, or provisioned for you.
`appUrl`	The URL you supplied, kept verbatim for display.
`kind`	`created` (Sente signed up) or `connected` (you own it, you supplied the credentials).
`username`	The login username. `null` on a `created` account until the run picks one.
`status`	`pending` → `active` on the first completed run; `failed`; `disabled` once revoked.
`revokedAt`	Timestamp, set when a connection is revoked. `null` otherwise.
`createdAt`	When the row was created.

kind is the whole security boundary between the two paths:

	`created`	`connected`
Who owns the account	Sente made it under the identity’s address	You did, before Sente existed
Credentials	Readable — `GET /v1/registrations/:id/credentials`	Write-only — `403 CREDENTIALS_WRITE_ONLY`
TOTP seed	Not supported	Optional, vaulted, never readable
Revocable	No (delete the identity to remove it)	Yes — revoke, or delete to purge the vault

The two never co-mingle at the same app. register over a connected account returns 409 ALREADY_CONNECTED; connect over a created one returns 409 ALREADY_REGISTERED.

The identity is plumbing

An identity is a real mailbox on sente.run. It exists so verification email has somewhere to land — and, for a created account, so the app has an address to sign up with. When you omit identityId, Sente derives the local part from the app’s hostname:

`appUrl`	Address provisioned	Identity `name`
`https://github.com/signup`	`github@sente.run`	`github.com`
`https://app.mailtrap.io/signin`	`app-mailtrap@sente.run`	`app.mailtrap.io`
`https://github.com/signup` (local part already taken)	`github-x7k2@sente.run`	`github.com`

Addresses are globally unique, so a taken local part gets a random suffix rather than an error. If the create then fails, the auto-provisioned identity is rolled back, so a failed connect doesn’t eat your plan’s identity cap.

Auto-provisioning is per call, not per app. Two connect calls for the same app with no identityId produce two identities and two separate accounts — and consume two identity slots. Keep the returned id (or pass identityId) when you mean “the account I already made”.

One account per (identity, app origin)

The uniqueness key is the identity plus the app’s origin — scheme, host and port, lowercased, path and query stripped.

https://app.example.com/signup and https://app.example.com/ are the same account.
https://example.com and https://app.example.com are different accounts.

That makes the create calls idempotent for one identity:

Situation	What happens
No account at that origin	Creates the row, queues a `register`/`connect` run.
A run is already in flight for the identity	Returns the existing account and that run — no second run.
Account is `active`, no live run	`register` returns it and its last run and drives nothing (use `login` to re-auth).
Account is `pending`/`failed`, no live run	Queues a fresh run on the same row (a retry).
An existing connection	`connect` rotates the credentials, clears any revoke, re-drives.

Runs and sessions serialize per identity: one run at a time, one live browser session. Ten accounts under ten identities work in parallel; ten under one identity queue behind each other.

When to pass `identityId`

You want	Do
An account, fast, and don’t care about the address	Omit it.
Several accounts to share one mailbox and one address	Create an identity once, pass its `id` every time.
A specific address (you told a vendor `billing-bot@sente.run`)	`identities.create({ localPart })`, then pass the `id`.
Maximum parallelism across apps	Omit it — one identity per account means runs never queue behind each other.
To rotate credentials on an existing connection	Pass the same `identityId` (or use `setCredentials` on the account id).

Creating one explicitly is a normal call:

sente identity create --name "billing-bot" --local-part billing-bot
# add --on-conflict suffix to auto-suffix instead of failing when the local part is taken

const identity = await sente.identities.create({ name: "billing-bot", localPart: "billing-bot" });
await sente.connections.connect({ identityId: identity.id, appUrl, credentials });

identity = sente.identities.create(name="billing-bot", local_part="billing-bot")
sente.connections.connect(identity_id=identity.id, app_url=app_url, username=u, password=p)

What is stored where

Secret / state	Lives on	Readable through the API
Password	The account, AES-256-GCM	`created`: yes (audited). `connected`: never.
TOTP seed	The account, AES-256-GCM	Never. Only the server computes codes from it.
Logged-in cookies / storage	The identity’s browser profile	Via Sessions — CDP or `storageState`.
Verification email, and every later email	The identity’s inbox	Via the messages API.

One consequence worth planning around: every app under one identity emails the same address. That is what makes verification work without per-app inbox plumbing — and why an identity shared across ten apps has one busy mailbox.

Failure paths

Status	Code	Means	Do
`409`	`ALREADY_CONNECTED`	You called `register` where a connection exists.	Use the connection; it’s the owner’s account.
`409`	`ALREADY_REGISTERED`	You called `connect` where Sente created the account.	Use `login` / `getSession` on that id.
`409`	`REVOKED`	The connection was revoked.	`connect` again to re-enable, or leave it off.
`400`	`BAD_TOTP_SEED`	The seed isn’t valid base32 or an `otpauth://` URI.	Re-copy it from the app’s “can’t scan?” text.
`403`	`CREDENTIALS_WRITE_ONLY`	Credential read on a `connected` account.	By design — you already hold that password.
`404`	—	`identityId` doesn’t exist in your org.	Check the id, or omit it.
`429`	`IDENTITY_LIMIT_EXCEEDED`	Auto-provisioning would exceed the plan’s identity cap.	Reuse an identity, delete unused ones (`DELETE /v1/identities/:id`), or upgrade.
`429`	`RUN_LIMIT_EXCEEDED`	Daily or monthly run cap. Failed runs never count.	Wait for the window, or upgrade. See Limits.

Next steps

Connect an account you own

The owner-authorized path: credentials in write-only, TOTP re-login, revoke at any time.

Register a new account

Where terms permit — including what reliably doesn’t work.

Sessions

Turn an account into a logged-in browser: CDP URL or Playwright storageState.

Runs

The job that does the logging in: lifecycle, statuses, error codes.

Get started

Runs

Email

Events & audit

Trust

Accounts

One call

The account

The identity is plumbing

One account per (identity, app origin)

When to pass `identityId`

What is stored where

Failure paths

Next steps

Connect an account you own

Register a new account

Sessions

Runs

​One call

​The account

​The identity is plumbing

​One account per (identity, app origin)

​When to pass identityId

​What is stored where

​Failure paths

​Next steps

Connect an account you own

Register a new account

Sessions

Runs

One call

The account

The identity is plumbing

One account per (identity, app origin)

When to pass `identityId`

What is stored where

Failure paths

Next steps