Connections - Sente

A connection gives Sente delegated access to an account you already own: you supply the credentials, Sente logs in with a browser run, keeps the session re-loginable, and vaults the credentials write-only. It is the owner-authorized counterpart to registering a new account. See the Connect guide. A connection is stored as a registration with kind: "connected", so it shares the registration endpoints: sessions, login, and session export live at /v1/registrations/:id/... using the connection’s id.

Known limits, stated up front:

SSO-only accounts cannot be connected. If the account signs in only via Google/Okta/etc. or passkeys, there is no username+password for Sente to use.
Authenticator (TOTP) 2FA re-logins autonomously — supply totpSeed and the server computes the 30-second code at login. The seed is vaulted encrypted and never reaches any model; only the server-side controller computes codes from it.
Email-code MFA needs a human in the interactive live view — unless you repoint the 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 (MFA_REQUIRED) and pages one.

Create a connection

POST /v1/connections

Field	Type	Required	Description
`identityId`	string	yes	The identity this connection hangs off.
`appUrl`	URL	yes	The app to log in to.
`credentials.username`	string	yes	Your username at the app.
`credentials.password`	string	yes	Your password. Vaulted encrypted, write-only.
`credentials.totpSeed`	string	no	The authenticator secret — bare base32 or a full `otpauth://` URI. Enables autonomous 2FA re-login.
`verifyToIdentity`	boolean	no	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. Re-posting for the same (identity, app origin) re-connects: rotates the vaulted credentials, clears any revoke, and re-drives — this is also how you rotate a password or re-enable a revoked connection.

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

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
  }
}

Errors:

Status	Code	When
`400`	`BAD_TOTP_SEED`	The `totpSeed` isn’t usable base32 / `otpauth://`. Rejected at enrollment rather than failing three re-logins later.
`409`	`ALREADY_REGISTERED`	A Sente-created account already exists at that origin for this identity. `connect` never overwrites it.
`429`	`RUN_LIMIT_EXCEEDED`	Daily or monthly run cap.
`404`	—	`identityId` not your org’s.

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

List connections

GET /v1/connections — optional ?identityId=.... Returns only kind: "connected" rows, each with latestRun.

curl https://api.sente.run/v1/connections \
  -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": "active",
    "revokedAt": null,
    "createdAt": "2026-07-21T08:30:00.000Z",
    "latestRun": { "id": "run_9e0f1a2b3c4d5e6f708192a3b4c5d6e7", "type": "connect", "status": "completed", "registrationId": "reg_2d3e4f5a6b7c808192a3b4c5d6e7f812", "error": null, "result": null, "liveViewUrl": "https://app.hyperbrowser.ai/live?...", "gatewaySessionId": "5c1d...", "createdAt": "2026-07-21T08:30:00.000Z", "endedAt": "2026-07-21T08:33:40.000Z" }
  }
]

Get a connection

GET /v1/connections/:id Returns the connection object. 404 for unknown ids, other orgs’ resources, and for registrations that aren’t connected.

Credentials are write-only

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

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

with status 403. You already hold your own password; Sente vaults it encrypted and only the server-side run controller ever decrypts it to log in. 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 updates answer 409 REVOKED, and sessions can no longer open (409 NOT_ACTIVE). The vault is kept, so re-enabling is a single POST /v1/connections away.

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"
}

Delete a connection

DELETE /v1/connections/:id Revoke and purge: the vaulted password and TOTP seed are erased. This is the offboarding guarantee — after delete, Sente holds no secrets for this account. The row itself remains (audit trail), still disabled.

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

Response: 204 with no body.

	Revoke	Delete
Delegation	withdrawn	withdrawn
Vaulted secrets (password, TOTP seed)	kept, encrypted	purged
Re-enable	`POST /v1/connections` again with credentials	`POST /v1/connections` again with credentials

Use revoke to pause a delegation you expect to restore; use delete when offboarding and Sente should hold nothing.

​Create a connection

​List connections

​Get a connection

​Credentials are write-only

​Revoke a connection

​Delete a connection