Connections and authorization

A connection is one user's account on one website, authorized by that user for your application. The auth link, the URL your product sends the user to, creates it. It lives until the user or you revoke it, and every agent you run is a call against one.

The auth link opens the connect page on connect.trywool.com. The sign-in happens there rather than in your product so that your product never holds the user's password. The user approves your application and supplies the details needed to sign in. WOOL completes the sign-in, and your product receives a token for the resulting connection. This authorization includes accepting the website's required sign-in agreements, including new or updated terms, and required consent from a sign-in provider. It does not include optional enrollment, subscriptions, purchases, or permissions unrelated to signing in. If the website asks the user to approve the sign-in on another device, the connect page shows the website's own instruction and waits for the approval.

The authorization, step by step

Some websites ask for more than a password, such as a choice of sign-in method or a one-time code. The connect page asks the user for the details or approvals WOOL needs to continue. Three outcomes are possible:

• The sign-in completes. WOOL redirects to your redirect_uri with code and state.
• The user declines. The redirect carries error=access_denied and state.
• The sign-in fails. The redirect carries error=server_error and state.

An authorization expires 15 minutes after it starts, so build the link when the user is about to open it.

Faster sign-in discovery over time

WOOL keeps a shared discovery cache of successful routes to a website's sign-in flow. For example, after learning that a website's account menu leads to its sign-in form, WOOL can reuse that route when another user connects through the same entry page and language. This reduces the work needed to find where sign-in begins.

These routes are shared across applications. A successful authorization through one product can help users of another product reach the same website's sign-in form sooner. As more users connect websites, successful discoveries add to or update the routes available for later connections. You don't need to configure this in your integration.

WOOL checks the current page before reusing a route. If the website has changed, it discovers the sign-in flow again. The time saved depends on the website and whether a matching route is available; each user still needs to authorize your application, sign in, and complete any required verification.

The shared cache contains navigation guidance, not passwords, one-time codes, saved sign-ins, execution prompts, or task results. This reuse applies to sign-in discovery. Once connected, each execution works from your prompt against that user's account.

Connection statuses

When the website signs the user out

When a run finds the account signed out, it fails with session_expired and the connection becomes REAUTHORIZATION_REQUIRED. New runs are refused until the user goes through the same auth link again. When they do, the connection returns to ACTIVE and the code exchange issues a new token. connection_id and user_id don't change, so you replace the stored token and carry on. Re-authorization covers the details.

Revoking a connection

Revoke from the console. Revocation ends any authorization in progress, revokes every token, and deletes the saved sign-in. Past executions remain readable. A run already in progress may still finish. To end a single token without touching the connection, use POST /v1/oauth/revoke.

Next steps

Executions explains what happens when you run a prompt against a connection.