Skip to content
Fous Docs
MarkdownStudio

Connect an account

Sign in to a website through Fous, from your code, your agent or Studio, or save a site's API key. Methods on that site then run with it.

A connection lets methods run with your organization's login on a site (session) or with the site's API key (api_key).

Connect a website login

Terminal
curl https://api.fous.com/v1/connections \  -H "Authorization: Bearer $FOUS_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "platform": "example.com",    "type": "session",    "attest": true  }'

attest: true confirms you may use the account. Add login_url if the sign-in page is not the obvious one. The answer is 201 with the first step:

JSON
{  "id": "conn_01m5kyvsdxea78rpr2j3qzzd1z",  "platform": { "name": "Example", "domain": "example.com" },  "type": "session",  "status": "pending",  "default": false,  "account_hint": null,  "connect_url": "https://app.fous.com/org_01M4CD7TVHDBPFQHZD05XMW5PB/connections?connect=conn_01m5kyvsdxea78rpr2j3qzzd1z",  "checked_at": null,  "created_at": "2026-10-26T09:42:14.000Z",  "sign_in": {    "status": "input",    "step_id": "stp_7h2k9q",    "message": "Enter your email or username and password to continue.",    "fields": [      { "id": "fld_1", "label": "Email or username", "type": "text", "required": true },      { "id": "fld_2", "label": "Password", "type": "password", "required": true }    ],    "choices": [],    "expires_at": "2026-10-26T09:52:14.000Z"  }}

Then either send the person to connect_url to sign in in Studio and wait with GET /v1/connections/{id}?wait=60 until it is active, or relay each step from your code.

Answer each step

sign_in.statusDo
workingWait with GET /v1/connections/{id}?wait=30.
inputSend values for fields, or one of choices.
approvalThe person approves on their phone, picking code. Wait as above.
failedStop. message says why.

Send fields keyed by field id, or "choice": "<choice id>":

Terminal
curl "https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z/sign-in" \  -H "Authorization: Bearer $FOUS_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "step_id": "stp_7h2k9q",    "fields": { "fld_1": "person@example.com", "fld_2": "their-password" }  }'

The answer is the next step, here a code sent by email:

JSON
{  "id": "conn_01m5kyvsdxea78rpr2j3qzzd1z",  "platform": { "name": "Example", "domain": "example.com" },  "type": "session",  "status": "pending",  "default": false,  "account_hint": null,  "connect_url": "https://app.fous.com/org_01M4CD7TVHDBPFQHZD05XMW5PB/connections?connect=conn_01m5kyvsdxea78rpr2j3qzzd1z",  "checked_at": null,  "created_at": "2026-10-26T09:42:14.000Z",  "sign_in": {    "status": "input",    "step_id": "stp_4n8w2c",    "message": "Enter the 6-digit code sent to p…@example.com.",    "fields": [{ "id": "fld_3", "label": "Code", "type": "code", "length": 6, "required": true }],    "choices": [],    "expires_at": "2026-10-26T09:53:02.000Z"  }}

A rejected answer returns the same step with rejected: true. For a link field, copy the link from the email without opening it, or it is used up.

  • A sign-in ends after 10 minutes without an answer, or 15 in all. An organization runs 2 at once.
  • 409 with reason step_expired: answer the current step. sign_in_busy: Fous is still on the last answer.
  • {"attest": true, "restart": true} on the sign-in endpoint starts over, for example to switch accounts. DELETE cancels.
  • Fous never returns or logs the values, and keeps only the identifier and password, sealed, to sign in again.

Which connection a run uses

An organization has one login per site; connecting the site again returns it with 200. A run uses the site's active connection, then the default, then the newest, unless it names connection. To set the default:

Terminal
curl -X PATCH "https://api.fous.com/v1/connections/conn_01m5kyvsdxea78rpr2j3qzzd1z" \  -H "Authorization: Bearer $FOUS_API_KEY" \  -H "Content-Type: application/json" \  -d '{"default": true}'
JSON
{  "id": "conn_01m5kyvsdxea78rpr2j3qzzd1z",  "platform": { "name": "Example", "domain": "example.com" },  "type": "session",  "status": "active",  "default": true,  "account_hint": "p…@example.com",  "checked_at": "2026-10-26T09:44:10.000Z",  "created_at": "2026-10-26T09:42:14.000Z"}

When the site signs the account out and Fous cannot sign back in, the connection turns needs_attention and runs answer 403 connection_required with connect_url.

Save a site's API key

Terminal
curl https://api.fous.com/v1/connections \  -H "Authorization: Bearer $FOUS_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "platform": "example.com",    "type": "api_key",    "api_key": "your-key-for-that-site",    "attest": true  }'
JSON
{  "id": "conn_01m5kz2b4d6f8h0k2m4p6r8t0v",  "platform": { "name": "Example", "domain": "example.com" },  "type": "api_key",  "status": "active",  "default": true,  "hint": "…site",  "checked_at": null,  "created_at": "2026-10-26T09:50:31.000Z"}

The key is stored encrypted, never returned, and sent only to its own site.

Disconnect

Only a person can, with Disconnect in Studio's Connections.