Skip to main content

Give agents website access

A customer asks your support agent "where is my order?". The answer isn't in any document. It's in your order admin, behind a login. The same goes for stock levels, ticket queues, partner dashboards: the freshest answers live in systems, not files.

Agents can go get those answers. You allow specific sites, store a login where the site needs one, and the agent browses like a teammate would, without the password ever appearing in a prompt or a spec.

One export makes the commands below paste as-is:

export APP_ID=your-application-id    # docana applications list

1. Allow a site​

Allowed websites belong to your company and are linked per application. Add one from the terminal. The output includes the site id you'll use next:

docana app "$APP_ID" allowed-websites create \
  -n "Partner Portal" \
  --url https://portal.example.com \
  --engine advanced

Pick the engine by what the site needs:

  • basic: a read-only fetch of the page. Fast and cheap, right for public pages.
  • advanced: a real headless browser. Needed for logins, JavaScript-heavy apps, and anything interactive.

docana app "$APP_ID" allowed-websites ls shows what's already allowed, including whether a login is stored:

ID        Name             URL                          Engine     Enabled   Stored creds
site_a1   Partner Portal   https://portal.example.com   ADVANCED   yes       [email protected] (pw ✓)

2. Store a login​

For sites behind authentication, attach credentials to the allowed website. Pipe the password from your secret manager so it never lands in your shell history:

op read "op://Team/Partner Portal/password" | \
  docana app "$APP_ID" allowed-websites set-credentials <site-id> \
  --username [email protected] \
  --password-stdin

The password is encrypted before storage. Agents log in with it during a browsing session. You never paste it into a spec or a prompt.

Use a dedicated account for agents where you can: it keeps their access auditable and lets you revoke it without touching anyone's personal login.

3. Sessions persist between runs​

Logging in on every run would be slow, so browsing sessions reuse a persistent browser context per application: cookies and login state carry over.

If a login goes stale or you rotated the password, reset the context and the next run logs in fresh:

docana browser-context reset --app-id "$APP_ID"

Manage it over the API​

Everything above is also plain HTTP, for provisioning from your own systems: POST /api/v1/applications/{id}/allowed-websites/ creates and links a site (a plain-text password in the body is encrypted before storage), and PATCH .../allowed-websites/{siteId}/ toggles the per-application link. See the API Reference for the full schemas.

Next steps​

  • CLI: The app commands used here, and everything else
  • Creating an Agent: Build the agent that will do the browsing
  • API Reference: The allowed-websites endpoints in full