# Connect an agent with browser approval

Release status: TP-169 implementation under verification; production availability
is recorded in the cumulative [Homebase handoff](https://www.tekpartner.app/agent-guides/tek-local-gateway.md).
Existing credentials and the MCP tool catalog are unchanged.

Give your agent this URL: **https://www.tekpartner.app/connect**.
The agent requests a connection; an active organization owner or administrator
reviews it in the browser. Its suggested name, purpose, permissions, projects,
expiry and review date are editable defaults. No access is granted until approval.

## For the agent or client

Use your own connection. Do not reuse another agent's credential or ask for a key
in chat. First check for a suitable existing connection and verify its `whoami`.
A new request always creates a distinct profile, never attaches to an existing
agent merely because the names match. Existing agent credentials continue to be
managed in the signed-in Agents page.

Download the official [Node connection client](https://www.tekpartner.app/agent-tools/connect.mjs)
to a local file, inspect it, then run with Node 22 or newer. Example:

```sh
node connect.mjs --name "Brix" --client "Jason's desktop agent" \
  --project "BevBridge" \
  --capability projects.read --capability work-items.read \
  --capability work-items.write --expires-in 30 --review-in 7
```

The project above is an example: suggest an actual project name or ID when known.
Repeat `--project` and `--capability` as needed. Default permissions are Projects
Read and Work Read; no project and no organization-wide access is assumed.
`--organization` explicitly suggests all organization information. The person can
change this before approval. `--expires-in 0` suggests until revoked. The review
date must be on or before a dated expiry; review is not automatic revocation.
Unsupported campaign, workflow, finance, platform, private-note and human-approval
powers are not available through this flow.

The client opens the browser and prints a comparison code. For a remote/headless
client, use `--no-browser` and share only the approval URL/code with the person.
They must verify the code, selected organization and restrictions themselves.
Do not approve on the person's behalf. If they lack administrator access, ask an
administrator in that organization to review the link before it expires.
Unmatched or ambiguous project suggestions stay unselected. They never expand to
organization-wide access. Approval with no project requires an explicit
organization-wide choice; otherwise choose a project first.

The request lasts ten minutes. Keep the client running. It retrieves an encrypted
credential, decrypts it locally, verifies the returned identity/organization and
saves a private JSON file under `~/.config/tekpartner/`. Use `--output` for an
explicit file in an existing private directory. It never overwrites an existing
file, edits another client's configuration, or prints the credential. On macOS
and Linux files use mode 0600; Windows creation removes inherited permissions and
grants the current user's SID access before writing the secret.

If interrupted, use `node connect.mjs --resume /absolute/path/to/pending-file.json`
with the private recovery path printed before dispatch. Keep this file private:
it contains the temporary private key and request token. Exact retries reuse the
same request, settings and key. It is removed after successful collection or an
observed decline. Expired files should be removed locally. If approval may have
completed but no key was saved, review/revoke the uncollected credential in Agents
before starting over. Do not blindly create another profile or replace a key.

Configure the selected client's private secret store from the saved credential
file without printing it or exposing it to a model. Keep it outside repositories.
Use endpoint `https://api.tekpartner.app/v3/mcp`. Refresh/reconnect the client's MCP
connection, then call `tekpartner_whoami` and `tekpartner_capabilities` with
`{"surface":"current_work"}`. Match the exact returned organization and agent IDs
before reading work. Test only permitted reads; an empty result is valid.

## Integrating the flow

The typed SDK exposes `startAgentOnboarding`, `reviewAgentOnboarding`,
`decideAgentOnboarding` and `pollAgentOnboarding`. Only start/poll are public-client
operations. Review/decision are human administrative browser-session operations,
not MCP tools or bearer-key powers.

- `POST /v3/agent-onboarding/requests`: fresh UUID `Idempotency-Key`, public RSA
  2048-bit SPKI key (exponent 65537), locally generated 32-byte base64url
  `requestToken`, and `proposal`. Save these exact retry inputs before sending.
- `POST /v3/agent-onboarding/poll`: `requestId` and private `requestToken` in the
  JSON body. Poll no faster than every five seconds; obey `429`/`Retry-After`.
  Pending/denied/unavailable states carry no organization records. Approved
  results contain IDs and an RSA-OAEP-SHA256 encrypted standard TekPartner key.
- The canonical browser page uses review and decision endpoints with the real
  session, trusted origin, active administrator membership, expected version and
  an exact decision retry key. Its edited policy is authoritative.

No private key or plain credential is stored in the onboarding request table.
Polling and comparison tokens are hashed. Approval creates the profile,
credential, audit and encrypted handoff atomically. The encrypted delivery can
replay only within the original ten-minute window and while the credential and
principal remain active. Expired requests are inaccessible and purged on the next
start; durable credentials and audit remain. Names/purpose are unverified client
input. No provider/model is involved. This is a product credential bootstrap with
a browser approval pattern, not an OAuth authorization-server implementation.

## Write useful linked records

After setup, read [Readable links to TekPartner records](https://www.tekpartner.app/agent-guides/agent-manual.md#readable-links-to-tekpartner-records).
Use discovered record IDs and descriptive Markdown links in shared work. Stored
files use `/app/documents?documentId=<id>`; repository filenames are not automatic
file references. Links never grant access or send mention notifications. Existing
agents should refresh the same manual/skill; this adds no MCP tool or permission.