Connections - Sente

A connection is the owner-authorized path: you supply the credentials for an account you already own, Sente logs in with a browser run, vaults the credentials write-only, and keeps the account re-loginable. It is the lower-risk counterpart to registering a new account — nothing is created at the app, and you can withdraw the delegation at any time. A connection is stored as a registration with kind: "connected", so it shares the registration endpoints. Sessions, re-login, credential writes, and session export live at /v1/registrations/:id/... and take the connection’s id.

Known limits, before you build against this:

SSO-only accounts cannot be connected. If the account signs in only through Google/Okta/etc. or a passkey, there is no username and password for Sente to use.
Authenticator (TOTP) 2FA re-logins without a human — supply credentials.totpSeed and the server computes the 30-second code at login. The seed is vaulted encrypted, is never returned by the API, and never reaches any model.
Email-code MFA needs a human in the live view — unless you repoint that account’s notification email to the identity’s Sente address and pass verifyToIdentity: true, in which case the code lands in Sente’s inbox and is injected automatically.
SMS codes always need a human. The run blocks with MFA_REQUIRED and pages one. There is no SMS channel.

Create a connection

POST /v1/connections

Field	Type	Required	Description
`identityId`	string	no	The identity this connection hangs off. Omit it and Sente auto-provisions one, local part derived from the app’s hostname — accounts are first-order; the identity is plumbing.
`appUrl`	URL	yes	The app to log in to. Its origin becomes the account’s key.
`credentials.username`	string	yes	The username or email you sign in with. Non-empty.
`credentials.password`	string	yes	Your password. Vaulted encrypted, write-only. Non-empty.
`credentials.totpSeed`	string	no	The authenticator secret — bare base32, or a full `otpauth://` URI. Enables 2FA re-login with no human.
`verifyToIdentity`	boolean	no	Assert that you have repointed this account’s notification email to the identity’s Sente address, so emailed login/2FA codes can be fetched and injected automatically. Default `false`.

Queues a connect run that logs in with the supplied credentials and marks the connection active on success.

curl -X POST https://api.sente.run/v1/connections \
  -H "Authorization: Bearer sk_sente_..." \
  -H "content-type: application/json" \
  -d '{
    "appUrl": "https://app.example.com",
    "credentials": {
      "username": "me@mycompany.com",
      "password": "my-real-password",
      "totpSeed": "JBSWY3DPEHPK3PXP"
    }
  }'

sente connect https://app.example.com \
  --username me@mycompany.com \
  --password 'my-real-password' \
  --totp-seed JBSWY3DPEHPK3PXP

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

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

// no identityId — the backing identity is provisioned for this app
const { connection, run } = await sente.connections.connect({
  appUrl: "https://app.example.com",
  credentials: {
    username: "me@mycompany.com",
    password: process.env.APP_PASSWORD!,
    totpSeed: process.env.APP_TOTP_SEED,
  },
});

// timeout is MILLISECONDS; waitForRun also stops on `blocked`
const final = await sente.runs.waitForRun(run.id, { timeout: 300_000 });
if (final.status === "blocked") {
  // MFA_REQUIRED: a code went to YOUR inbox or phone — enter it at liveViewUrl, then resume
  console.log(final.error?.code, final.liveViewUrl);
  await sente.runs.resume(run.id);
}
console.log(connection.id, final.status);

import os
from sente import Sente

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

# no identity_id — the backing identity is provisioned for this app
connection, run = sente.connections.connect(
    app_url="https://app.example.com",
    username="me@mycompany.com",
    password=os.environ["APP_PASSWORD"],
    totp_seed=os.environ.get("APP_TOTP_SEED"),
)

# timeout is SECONDS; wait_for_run also stops on `blocked`
final = sente.runs.wait_for_run(run.id, timeout=300)
if final.status == "blocked":
    # MFA_REQUIRED: a code went to YOUR inbox or phone — enter it at live_view_url, then resume
    print(final.error, final.live_view_url)
    sente.runs.resume(run.id)
print(connection.id, final.status)

Response 201:

{
  "connection": {
    "id": "reg_2d3e4f5a6b7c808192a3b4c5d6e7f812",
    "identityId": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
    "appUrl": "https://app.example.com",
    "kind": "connected",
    "username": "me@mycompany.com",
    "status": "pending",
    "revokedAt": null,
    "createdAt": "2026-07-21T08:30:00.000Z"
  },
  "run": {
    "id": "run_9e0f1a2b3c4d5e6f708192a3b4c5d6e7",
    "type": "connect",
    "status": "queued",
    "registrationId": "reg_2d3e4f5a6b7c808192a3b4c5d6e7f812",
    "error": null,
    "result": null,
    "liveViewUrl": null,
    "gatewaySessionId": null,
    "createdAt": "2026-07-21T08:30:00.000Z",
    "endedAt": null
  }
}

verifyToIdentity is an HTTP-only field today. The TypeScript SDK, the Python SDK, and the CLI all send appUrl + credentials (and an optional identityId) but do not expose it — call the endpoint directly if you need it.

Re-connecting rotates credentials

Posting again for the same (identity, app origin) re-connects the existing row: it replaces the vaulted username, password, and TOTP seed, clears any revoke, resets the status to pending, and drives a fresh connect run. That single behaviour covers three jobs — rotating a password, adding or replacing a TOTP seed, and re-enabling a revoked connection. Omitting totpSeed on a re-connect clears the vaulted seed; resend it if the account still has authenticator 2FA.

Errors

Status	Code	What it means	What to do
`400`	—	A field failed validation — missing/empty `username` or `password`, or a bad `appUrl`; `error` is the zod issue array.	Both credentials are required: connect logs in, it does not create.
`400`	`BAD_TOTP_SEED`	The `totpSeed` isn’t usable base32 or a parseable `otpauth://` URI. Rejected at enrollment rather than failing three re-logins later.	Copy the secret from the app’s “can’t scan the QR code?” link.
`404`	—	`identityId` was given but isn’t your org’s.	Drop it and let Sente provision one, or pass a valid id.
`409`	`ALREADY_REGISTERED`	A Sente-created account already exists at that origin for this identity.	Connect never overwrites it. Use a different identity, or work with the existing account.
`429`	`IDENTITY_LIMIT_EXCEEDED`	`identityId` was omitted and auto-provisioning would cross the plan’s identity cap; `limit` is the cap.	Pass an existing `identityId`, delete an unused identity, or upgrade. Nothing is connected and no run is queued.
`429`	`RUN_LIMIT_EXCEEDED`	Daily or monthly run cap.	Retry after the window rolls, or upgrade.

The mirror-image conflict — register against an existing connection — is 409 ALREADY_CONNECTED on POST /v1/registrations.

If the connect fails on an identity Sente auto-provisioned for this call, that identity is deleted again — a failed connect doesn’t consume your identity cap.

List connections

GET /v1/connections

Query param	Type	Required	Description
`identityId`	string	no	Scope to one identity. Omitted → every connection in the org.

Returns only kind: "connected" rows, newest first, each with latestRun.

curl https://api.sente.run/v1/connections \
  -H "Authorization: Bearer sk_sente_..."

[
  {
    "id": "reg_2d3e4f5a6b7c808192a3b4c5d6e7f812",
    "identityId": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
    "appUrl": "https://app.example.com",
    "kind": "connected",
    "username": "me@mycompany.com",
    "status": "active",
    "revokedAt": null,
    "createdAt": "2026-07-21T08:30:00.000Z",
    "latestRun": {
      "id": "run_9e0f1a2b3c4d5e6f708192a3b4c5d6e7",
      "type": "connect",
      "status": "completed",
      "registrationId": "reg_2d3e4f5a6b7c808192a3b4c5d6e7f812",
      "error": null,
      "result": { "answer": "STATE: LOGGED_IN" },
      "liveViewUrl": "https://app.hyperbrowser.ai/live?...",
      "gatewaySessionId": "5c1d...",
      "createdAt": "2026-07-21T08:30:00.000Z",
      "endedAt": "2026-07-21T08:33:40.000Z"
    }
  }
]

Passing an identityId that isn’t your org’s returns 404 {"error": "identity not found"}.

Get a connection

GET /v1/connections/:id

curl https://api.sente.run/v1/connections/reg_2d3e4f5a6b7c808192a3b4c5d6e7f812 \
  -H "Authorization: Bearer sk_sente_..."

Response 200: the connection object. 404 {"error": "not found"} for unknown ids, other orgs’ resources, and for registration ids that are created rather than connected — this endpoint is kind-scoped, so use GET /v1/registrations/:id for those.

Credentials are write-only

There is no credential read for connections. GET /v1/registrations/:id/credentials on a connected account returns 403:

{ "error": "connected-account credentials are write-only", "code": "CREDENTIALS_WRITE_ONLY" }

You already hold your own password. Sente vaults it encrypted, and only the server-side run controller decrypts it, at login time, to type it into the app. The vaulted TOTP seed is treated the same way and is never returned by any endpoint. To rotate a credential, re-post POST /v1/connections with the new one.

Revoke a connection

POST /v1/connections/:id/revoke Withdraws the delegation. The connection becomes disabled: login and credential writes answer 409 REVOKED, and sessions refuse to open with 409 NOT_ACTIVE. The vault is kept, so re-enabling is one POST /v1/connections away. No body.

curl -X POST https://api.sente.run/v1/connections/reg_2d3e4f5a6b7c808192a3b4c5d6e7f812/revoke \
  -H "Authorization: Bearer sk_sente_..."

Response 200:

{
  "id": "reg_2d3e4f5a6b7c808192a3b4c5d6e7f812",
  "identityId": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
  "appUrl": "https://app.example.com",
  "kind": "connected",
  "username": "me@mycompany.com",
  "status": "disabled",
  "revokedAt": "2026-07-25T14:00:00.000Z",
  "createdAt": "2026-07-21T08:30:00.000Z"
}

Revoking is idempotent in effect — revoking an already-revoked connection returns it with a refreshed revokedAt. Writes a connection.revoke audit event.

Revoke stops Sente from logging in again. It does not invalidate a storageState you already exported, and it does not sign the account out at the app. If the account may be compromised, change the password at the app itself.

Delete a connection

DELETE /v1/connections/:id Revoke and purge: the vaulted password and TOTP seed are erased. This is the offboarding guarantee — afterwards Sente holds no secret for this account. The row itself remains, disabled, so the audit trail and the origin slot survive.

curl -X DELETE https://api.sente.run/v1/connections/reg_2d3e4f5a6b7c808192a3b4c5d6e7f812 \
  -H "Authorization: Bearer sk_sente_..."

Response: 204 with no body. Writes a connection.delete audit event.

	Revoke	Delete
Delegation	withdrawn	withdrawn
Vaulted password + TOTP seed	kept, encrypted	purged
Re-enable	`POST /v1/connections` with credentials	`POST /v1/connections` with credentials
Audit event	`connection.revoke`	`connection.delete`

Use revoke to pause a delegation you expect to restore; use delete when offboarding and Sente should hold nothing. Both are connected-only — calling either with a created registration’s id returns 404.

Connect an account

The guide, including the 2FA paths.

Human takeover

What happens when a code goes to your phone.

Security

How the vault and the audit trail work.

​Create a connection

​Re-connecting rotates credentials

​Errors

​List connections

​Get a connection

​Credentials are write-only

​Revoke a connection

​Delete a connection

​Related

Connect an account

Human takeover

Security

Create a connection

Re-connecting rotates credentials

Errors

List connections

Get a connection

Credentials are write-only

Revoke a connection

Delete a connection

Related