Registrations

A registration is an account at one app, keyed by that app’s URL origin. POST /v1/registrations starts a browser run that fills the app’s own signup form and completes email verification from the account’s own inbox; when it finishes you have a durable account you can re-login, hand to a browser, or export as a session. The same endpoints serve both kinds of account: created (Sente signed it up) and connected (you own it and supplied the credentials — see Connections). Sessions, re-login, credential writes, and session export all live here and take either id.

Register only at apps whose terms permit automated account creation — see Acceptable use. Pass confirmBeforeSubmit: true to keep a person on the final click. CAPTCHAs and SMS verification are not automated: the run stops, pages a human with an interactive live view, and waits. Nothing is worked around.

The registration object

{
  "id": "reg_1c2d3e4f5a6b708192a3b4c5d6e7f801",
  "identityId": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
  "appUrl": "https://app.example.com/signup",
  "kind": "created",
  "username": "acme-qa@sente.run",
  "status": "pending",
  "revokedAt": null,
  "createdAt": "2026-07-20T11:00:00.000Z"
}

Field	Description
`kind`	`created` (Sente made the account) or `connected` (you own it).
`status`	`pending` → no confirmed account yet · `active` → a run confirmed the login · `failed` → a run failed while still pending · `disabled` → a connection was revoked. An `active` account is never demoted by a later failed run.
`username`	The username at the app, once known. Passwords are never in this object — see credentials.
`revokedAt`	Set when a connection is revoked; `null` otherwise.

One registration exists per (identity, app origin). https://app.example.com/signup and https://app.example.com/ are the same registration; example.com and app.example.com are different ones.

Register at an app

POST /v1/registrations

Field	Type	Required	Description
`identityId`	string	no	The identity that will own the account. Omit it and Sente auto-provisions one, local part derived from the app’s hostname.
`appUrl`	URL	yes	Where to sign up. Its origin becomes the account’s key.
`credentials`	`{ username?, password? }`	no	Use these at the app. Omit the password and Sente generates a strong one and vaults it.
`confirmBeforeSubmit`	boolean	no	Agent fills the form, then blocks with `SUBMIT_CONFIRMATION_REQUIRED` and a live view so a human clicks the final submit. Default `false`.

Returns 201 with the registration and the run driving it.

curl -X POST https://api.sente.run/v1/registrations \
  -H "Authorization: Bearer sk_sente_..." \
  -H "content-type: application/json" \
  -d '{
    "appUrl": "https://app.example.com/signup",
    "confirmBeforeSubmit": true
  }'

# waits for the run and prints the outcome; --no-wait returns the run id immediately
sente register https://app.example.com/signup --confirm-before-submit

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 { registration, run } = await sente.registrations.register({
  appUrl: "https://app.example.com/signup",
  confirmBeforeSubmit: true,
});

// waitForRun stops on completed | failed | blocked; timeout is MILLISECONDS
const final = await sente.runs.waitForRun(run.id, { timeout: 300_000 });
if (final.status === "blocked") {
  console.log("a human is needed:", final.error?.code, final.liveViewUrl);
} else {
  console.log(registration.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
registration, run = sente.registrations.register(
    app_url="https://app.example.com/signup",
    confirm_before_submit=True,
)

# wait_for_run stops on completed | failed | blocked; timeout is SECONDS
final = sente.runs.wait_for_run(run.id, timeout=300)
if final.status == "blocked":
    print("a human is needed:", final.error, final.live_view_url)
else:
    print(registration.id, final.status)

{
  "registration": {
    "id": "reg_1c2d3e4f5a6b708192a3b4c5d6e7f801",
    "identityId": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
    "appUrl": "https://app.example.com/signup",
    "kind": "created",
    "username": null,
    "status": "pending",
    "revokedAt": null,
    "createdAt": "2026-07-20T11:00:00.000Z"
  },
  "run": {
    "id": "run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6",
    "type": "register",
    "status": "queued",
    "registrationId": "reg_1c2d3e4f5a6b708192a3b4c5d6e7f801",
    "error": null,
    "result": null,
    "liveViewUrl": null,
    "gatewaySessionId": null,
    "createdAt": "2026-07-20T11:00:00.000Z",
    "endedAt": null
  }
}

Poll GET /v1/runs/:id or subscribe to the run.* webhooks for the outcome.

Idempotency

The call converges instead of erroring. Re-posting the same (identity, app origin):

Existing state	What you get back
No registration	A new `pending` registration and a fresh `register` run.
A run is already in flight for this identity	The existing registration and that run — no second browser is started.
Registration `active`, nothing running	The registration and its most recent run. Nothing is re-driven — use `POST /:id/login` to re-authenticate.
Registration `pending` or `failed`, nothing running	The same registration row and a new `register` run (a retry).

Errors

Status	Code	What it means	What to do
`400`	—	`appUrl` isn’t a valid URL, or a field failed validation; `error` is the zod issue array.	Send an absolute `http(s)` URL.
`404`	—	`identityId` was given but isn’t your org’s.	Drop `identityId` and let Sente provision one, or pass a valid id.
`409`	`ALREADY_CONNECTED`	This identity already has a connected (owner-supplied) account at that origin.	Registering would clobber the owner’s account, so it is refused. Use `POST /v1/registrations/:id/login` on the existing account instead.
`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` to reuse an address, delete an unused identity, or upgrade. No account is created and no run is queued.
`429`	`RUN_LIMIT_EXCEEDED`	The daily or monthly run cap; `limit` is the one that tripped.	Retry after the window rolls, or upgrade. Failed runs don’t count, so this reflects real work.

When identityId is omitted and the registration itself then fails, the auto-provisioned identity is deleted again — a failed call doesn’t quietly consume your identity cap.

List registrations

GET /v1/registrations

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

Each row embeds latestRun (a full run object, or null) so a dashboard can render status without a second call. Newest first.

curl "https://api.sente.run/v1/registrations?identityId=idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5" \
  -H "Authorization: Bearer sk_sente_..."

[
  {
    "id": "reg_1c2d3e4f5a6b708192a3b4c5d6e7f801",
    "identityId": "idt_9f1c2ab34d5e46f7a8b9c0d1e2f3a4b5",
    "appUrl": "https://app.example.com/signup",
    "kind": "created",
    "username": "acme-qa@sente.run",
    "status": "active",
    "revokedAt": null,
    "createdAt": "2026-07-20T11:00:00.000Z",
    "latestRun": {
      "id": "run_8d9e0f1a2b3c4d5e6f708192a3b4c5d6",
      "type": "register",
      "status": "completed",
      "registrationId": "reg_1c2d3e4f5a6b708192a3b4c5d6e7f801",
      "error": null,
      "result": { "answer": "STATE: LOGGED_IN" },
      "liveViewUrl": "https://app.hyperbrowser.ai/live?...",
      "gatewaySessionId": "3f6a9b2c-...",
      "createdAt": "2026-07-20T11:00:00.000Z",
      "endedAt": "2026-07-20T11:03:12.500Z"
    }
  }
]

The list includes both kinds. Filter client-side on kind, or use GET /v1/connections for connected accounts only. Passing an identityId that isn’t your org’s returns 404 {"error": "identity not found"}.

Get a registration

GET /v1/registrations/:id

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

Response 200: the registration object (no latestRun). 404 {"error": "not found"} otherwise.

Log in again

POST /v1/registrations/:id/login Queues a login run that re-authenticates with the vaulted credentials, completing email verification from the account’s own inbox if the app sends a code, and injecting a TOTP code server-side if a seed is vaulted. Works for created and connected accounts. No body.

curl -X POST https://api.sente.run/v1/registrations/reg_1c2d3e4f5a6b708192a3b4c5d6e7f801/login \
  -H "Authorization: Bearer sk_sente_..."

Response 201: { "registration": { … }, "run": { …, "type": "login", "status": "queued" } }. If a run is already in flight for that identity, you get that run back instead of a second one.

Status	Code	What it means	What to do
`409`	`REVOKED`	The account is a revoked connection; the delegation was withdrawn.	Re-enable it with `POST /v1/connections` and fresh credentials.
`429`	`RUN_LIMIT_EXCEEDED`	Daily or monthly run cap.	Retry later or upgrade.
`404`	—	Unknown id, or not your org’s.	—

Open a logged-in browser session

POST /v1/registrations/:id/session Opens a browser on the identity’s persistent profile — already signed in to this app — and returns a CDP URL for chromium.connectOverCDP (Playwright) or puppeteer.connect. Conceptual walkthrough: Sessions. The login is verified by recency, not by inspecting the page: if the last confirmed login is within the freshness window (10 minutes by default), the session opens immediately; if it is older, Sente queues a re-login run and answers 409 SESSION_STALE with the runId to poll before retrying.

Body field	Type	Description
`verify`	boolean	`false` skips the freshness check and opens the profile as-is. Faster, but the login may already have expired at the app.
`maxStaleSec`	number	Override the freshness window for this call, in seconds.

curl -X POST https://api.sente.run/v1/registrations/reg_1c2d3e4f5a6b708192a3b4c5d6e7f801/session \
  -H "Authorization: Bearer sk_sente_..." \
  -H "content-type: application/json" \
  -d '{}'

Response 201:

{
  "sessionId": "3f6a9b2c-...",
  "cdpUrl": "wss://connect.hyperbrowser.ai?token=...",
  "liveViewUrl": "https://app.hyperbrowser.ai/live?...",
  "expiresAt": "2026-07-20T11:25:00.000Z",
  "verified": true,
  "healed": false
}

verified and healed are present only on the default (verified) path — with verify: false the response carries sessionId, cdpUrl, liveViewUrl, and expiresAt alone. The cdpUrl is returned once and never stored; a new session mints a new one. One live session per identity, and it is mutually exclusive with runs — both drive the same browser profile.

The SDK method registrations.getSession(id) (get_session in Python) already implements the 409-poll-retry loop: it waits out the re-login run and returns the session, with healed: true when a re-login happened. Use it instead of writing the loop yourself.

Status	Code	What it means	What to do
`409`	`SESSION_STALE`	The last confirmed login is older than the freshness window; a re-login run was queued. Carries `runId`.	Poll that run to `completed`, then retry the call.
`409`	`SESSION_PENDING`	A run is already in flight for this identity. Carries `runId`.	Poll that run, then retry.
`409`	`SESSION_ALREADY_OPEN`	This identity already has an open session; the response carries its `sessionId`.	Use it, or `DELETE` it first.
`409`	`IDENTITY_BUSY`	A run is using the identity’s browser profile right now.	Wait for the run to end.
`409`	`NOT_ACTIVE`	The account isn’t `active` — never confirmed, failed, or revoked.	Run `register`/`login`, or re-connect a revoked connection.
`409`	`NO_PROFILE`	No browser profile exists yet; no run has ever logged this identity in.	Complete a register or login run first.
`404`	—	Unknown registration, or its identity is gone.	—

Close the session

DELETE /v1/registrations/:id/session Stops the identity’s open browser session and frees the slot. Idempotent — closing when nothing is open still returns 204. Sessions bill per minute while open, so close them.

curl -X DELETE https://api.sente.run/v1/registrations/reg_1c2d3e4f5a6b708192a3b4c5d6e7f801/session \
  -H "Authorization: Bearer sk_sente_..."

Response: 204 with no body.

Export session state

POST /v1/registrations/:id/session/export Returns a portable Playwright storageState (cookies + localStorage) for the logged-in account, loadable into your own Playwright, Puppeteer, or browser-use — no Sente browser needed afterwards. Takes the same verify / maxStaleSec body and the same 409 SESSION_STALE / SESSION_PENDING contract as /session. If a session is already open, Sente exports from it and leaves it open. Otherwise it opens one, exports, and closes it again.

curl -X POST https://api.sente.run/v1/registrations/reg_1c2d3e4f5a6b708192a3b4c5d6e7f801/session/export \
  -H "Authorization: Bearer sk_sente_..." \
  -H "content-type: application/json" \
  -d '{}'

Response 200:

{
  "storageState": {
    "cookies": [ { "name": "session", "value": "...", "domain": "app.example.com", "path": "/", "expires": 1795000000, "httpOnly": true, "secure": true, "sameSite": "Lax" } ],
    "origins": [ { "origin": "https://app.example.com", "localStorage": [ { "name": "token", "value": "..." } ] } ]
  }
}

The export is a bearer credential for a logged-in account — anyone holding it is signed in as that account, and Sente cannot revoke it. Store it like a password. Every export writes a session.export audit event.

Get credentials

GET /v1/registrations/:id/credentials For Sente-created accounts: returns the vaulted username and password in plaintext, because the password is one Sente generated and you have no other copy. Every read writes a credentials.read audit event.

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

Response 200:

{
  "username": "acme-qa@sente.run",
  "password": "kV9#mQ2...",
  "origin": "generated"
}

origin is generated (Sente made the password) or supplied (you provided it). Any field may be null if it was never set.

Status	Code	What it means	What to do
`403`	`CREDENTIALS_WRITE_ONLY`	The account is `connected`. Owner-supplied credentials are never read back out of the vault — only the server-side run controller decrypts them to log in.	You already hold this password. To change it, re-post `POST /v1/connections`.
`404`	—	Unknown id, or not your org’s.	—

Update credentials

PUT /v1/registrations/:id/credentials

Field	Type	Required	Description
`username`	string	no	New username to vault.
`password`	string	no	New password to vault.

This overwrites the vault only. It does not change the password at the app. Use it after you rotate the password at the app yourself — otherwise the vault and the app desync and the next login run fails.

curl -X PUT https://api.sente.run/v1/registrations/reg_1c2d3e4f5a6b708192a3b4c5d6e7f801/credentials \
  -H "Authorization: Bearer sk_sente_..." \
  -H "content-type: application/json" \
  -d '{"password": "the-password-i-just-set-at-the-app"}'

Response: 204 with no body. Writes a credentials.write audit event. Returns 409 {"code": "REVOKED"} if the account is disabled (a revoked connection).

Register an account

The guide, with the human-in-the-loop path.

Sessions

CDP handoff, freshness, and storageState.

Runs

Watch, resume, or abort what this started.

​The registration object

​Register at an app

​Idempotency

​Errors

​List registrations

​Get a registration

​Log in again

​Open a logged-in browser session

​Close the session

​Export session state

​Get credentials

​Update credentials

​Related

Register an account

Sessions

Runs

The registration object

Register at an app

Idempotency

Errors

List registrations

Get a registration

Log in again

Open a logged-in browser session

Close the session

Export session state

Get credentials

Update credentials

Related