# Connections

> Name each account your code and agents act in, let your users connect it once, and use it by name.

A **connection** is one account on another service, under a name you choose: Ana's Gmail as `gmail`, Acme's Stripe as `stripe`. Your code, your toolkits and your agents name the connection, so they always act in exactly that account. Your users connect their own accounts through a page NoClick hosts, and you never see or store their tokens. NoClick keeps OAuth tokens fresh and checks that each connection works.

## Create a connection

```python
import noclick

user = noclick.User.from_id("user_42", create_if_missing=True)
with noclick.as_user(user):
    gmail = noclick.Connection.from_name(
        "gmail",
        integration="gmail",
        create_if_missing=True,
        reason="to send your weekly summaries",
        redirect_url="https://app.example.com/settings/connections",
    )
    print(gmail.status, gmail.connect_url)   # pending https://noclick.com/credential/provide/...
```

```ts
import { Connection, User, asUser } from "noclick";

const user = User.fromId("user_42", { createIfMissing: true });
await asUser(user, async () => {
  const gmail = await Connection.fromName("gmail", {
    integration: "gmail",
    createIfMissing: true,
    reason: "to send your weekly summaries",
    redirectUrl: "https://app.example.com/settings/connections",
  }).hydrate();
  console.log(gmail.status, gmail.connectUrl);   // pending https://noclick.com/credential/provide/...
});
```

A [user](https://www.noclick.com/docs/guide/users.md) is your own id for someone your product acts for, and every call inside `as_user` acts for them: `from_id` with `create_if_missing=True` creates them the first time it's used. Once they exist, `as_user("user_42")` takes the id alone, as the rest of this guide does.

A new connection is **pending**: no account is connected yet, and `connect_url` is the page where the user signs in to the service. Show it in your product (a "Connect Gmail" button is typical). `reason` appears on the page, so tell the user why you're asking. When they finish, NoClick sends them to your `redirect_url` with `status=success` in the query string.

An operation that needs no account, like Exa's web search, needs no connection at all: name it `"exa.search"` in tools, or run it with `noclick.run`. A connection named `exa` holding your own key makes the same names use your key: see [Operations on NoClick's key](https://www.noclick.com/docs/guide/integrations.md#operations-on-noclick-s-key).

`from_name` is lazy: nothing is sent until you use the connection, and with `create_if_missing=True` that first use creates it if it doesn't exist, so the same line works for a new user and a returning one. `integration` says what the connection is, so it's checked: a connection of that name for another integration raises `noclick.Conflict` naming it. `noclick.Connection.create` always creates, and raises `noclick.Conflict` if the name is taken; with `allow_existing=True` it returns the connection already there, as it is.

A name is 1 to 32 lowercase letters, digits, `-` and `_`, unique for each user (and among your account's own connections). `search`, `fetch` and `code` are the built-in tools' names and can't be used.

## Two accounts on one service

A user with two Gmail accounts has two connections:

```python
with noclick.as_user("user_42"):
    work = noclick.Connection.from_name("work-gmail", integration="gmail", create_if_missing=True)
    home = noclick.Connection.from_name("home-gmail", integration="gmail", create_if_missing=True)
```

```ts
import { Connection, asUser } from "noclick";

await asUser("user_42", async () => {
  const work = Connection.fromName("work-gmail", { integration: "gmail", createIfMissing: true });
  const home = Connection.fromName("home-gmail", { integration: "gmail", createIfMissing: true });
});
```

A toolkit or agent given both gets both sets of tools and picks per call.

## Wait for the user

```python
gmail.wait()           # returns once an account is connected
print(gmail.account)   # ana@example.com: the account it reaches
```

```ts
await gmail.wait();          // returns once an account is connected
console.log(gmail.account);  // ana@example.com: the account it reaches
```

`account` names the account it reaches as the app's Connections list does: its login, else its email, else who a check verified it as, else the number it links; `None` (`null`) when none of them is known.

`wait()` returns at once when the connection is already connected. It waits on the connection, not on one link: an account connected through any of its links ends the wait, and when a link lapses after you made a fresh one (`connect_link()` or `request()`, from any process), it keeps waiting on the fresh one. It raises `noclick.OperationExpired` when the open link lapses and no fresh one was made. In a web server, don't block a request on it: check `gmail.refresh().connected` later, or wait in a background job.

## Send the link for you

`request()` emails a fresh link to the user. `connect_link()` makes one without sending it, or sends it where `send_to` says: `"user"`, or, only from code that isn't acting for a user, `"owner"` (your account's owner) or another email address. A connection of your account's own has no user, so `request()` on one takes `send_to="owner"` or an email; its default, `"user"`, raises `noclick.InvalidRequest`.

```python
link = gmail.request(reason="to post your team's standup")
print(link.url)
print(link.delivered_via)   # ["email"]
print(link.undelivered)     # channels that failed, each with a reason
```

```ts
const link = await gmail.request({ reason: "to post your team's standup" });
console.log(link.url);
console.log(link.deliveredVia);   // ["email"]
console.log(link.undelivered);    // channels that failed, each with a reason
```

Links go out by email only. For a user with no email address, `send_to` raises `noclick.InvalidRequest` before anything is created: make the link without `send_to` and pass `link.url` on yourself. The new link is the connection's own from then on, so `gmail.connect_url` is its `url`. A link is also an [operation](https://www.noclick.com/docs/guide/operations.md): `link.wait()` returns the connected `Connection`.

## Use it

```python
gmail.run("send_email_message", {
    "to": ["ana@example.com"],
    "subject": "Your weekly summary",
    "body": "Three invoices were paid this week.",
})
```

```ts
await gmail.run("send_email_message", {
  to: ["ana@example.com"],
  subject: "Your weekly summary",
  body: "Three invoices were paid this week.",
});
```

[Calling integrations](https://www.noclick.com/docs/guide/integrations.md) covers what a connection can do (`operations()` and `operation()`), `run` and `lookup`. To hand a connection to a model, list it in a [toolkit](https://www.noclick.com/docs/guide/toolkits.md) or in an [agent's tools](https://www.noclick.com/docs/guide/agents.md). A name there is a connection in the scope the tools run in, else the integration of that name, limited to its operations that need no account.

## Share one across users

A connection belongs to one scope, a user or your account, and a name in an agent's tools always means the agent's own user's connection. To give an agent a connection from another scope, pass the `Connection` object itself: it stays that connection, wherever the agent lives. That's how you build what your product needs on top of users: a company whose people share its Slack, or your own support mailbox in every user's agent.

```python
import noclick

team_slack = noclick.Connection.from_name("team-slack", user="acme")   # the company's, connected once
with noclick.as_user("dana"):
    assistant = noclick.Agent.from_name(
        "assistant",
        create_if_missing=True,
        instructions="You help Dana with her email, and post updates to her team.",
        tools=["gmail", team_slack.only("send_message_to_channel")],
    )
```

```ts
import { Agent, Connection, asUser } from "noclick";

const teamSlack = Connection.fromName("team-slack", { user: "acme" });   // the company's, connected once
await asUser("dana", async () => {
  const assistant = Agent.fromName("assistant", {
    createIfMissing: true,
    instructions: "You help Dana with her email, and post updates to her team.",
    tools: ["gmail", teamSlack.only("send_message_to_channel")],
  });
});
```

`"gmail"` is Dana's own connection; `team_slack` stays Acme's. Your account's own connections share the same way:

```python
import noclick

support_mail = noclick.Connection.from_name("support-gmail")   # your account's
with noclick.as_user("user_42"):
    assistant = noclick.Agent.from_name(
        "assistant", create_if_missing=True,
        instructions="When the user needs a person, email our support team.",
        tools=[support_mail.only("send_email_message"), "search"],
    )
```

```ts
import { Agent, Connection, asUser } from "noclick";

const supportMail = Connection.fromName("support-gmail");   // your account's
await asUser("user_42", async () => {
  const assistant = Agent.fromName("assistant", {
    createIfMissing: true,
    instructions: "When the user needs a person, email our support team.",
    tools: [supportMail.only("send_email_message"), "search"],
  });
});
```

What holds when you share one:

- **Only your account decides.** Only a key that acts for your whole account (the `NoClick-User` header is fine) can put another scope's connection in an agent's, a toolkit's or a hosted MCP server's tools, or make it an agent's `model_connection`. A key pinned to a user, a [session](https://www.noclick.com/docs/guide/sessions.md), an app's code or an agent's own NoClick tools raises `noclick.PermissionDenied`, before anything is looked up, so no user (and no model) can reach another's accounts on their own. They may keep what you gave, or narrow it (one of its operations, an argument bound), never widen it, and a spawned child gets it only as its parent holds it.
- **The agent's user never gets the connection.** Not by its id, not its token, not a run of one of its operations, and not its connect link: while it's pending or disconnected, its tools tell the agent it's unavailable, and its own user reconnects it.
- **Tool names stay unique.** The model tells a shared connection apart by its name (in a toolkit, `team-slack__send_message_to_channel`), so an agent or a toolkit can't hold two connections of one name: name company connections apart, like `team-slack`.
- **The owner approves.** A call is judged by your account's [approval rules](https://www.noclick.com/docs/guide/policy.md) and by the rules of the agent's user and the connection's user, and the strictest one decides. A held call is approved by the connection's owner: its user, or your account's owner for your account's connection.
- **The agent's user pays.** Its calls count toward the spend cap of the user the agent acts for, and show in both users' activity (`noclick.ToolCall.list(user_filter=...)` for either).
- **Taking it back.** Take it out of the tools, or delete or reconnect the connection itself. `used_by` on a connection lists every agent and hosted MCP server that has it in their tools, from any scope.

A toolkit takes the same objects. A toolkit you build once and use for every user keeps resolving names among each user's connections, while a shared connection stays itself: see [Toolkits](https://www.noclick.com/docs/guide/toolkits.md).

## Fix arguments the model mustn't choose

An agent that reads email can be told, by an email, to send your user's data somewhere else. `bind(...)` on some of a connection's operations takes that choice away: a bound parameter leaves the tool's schema, so the model never sees or sets it, and NoClick fills it on every call.

```python
import noclick

with noclick.as_user("user_42"):
    gmail = noclick.Connection.from_name("gmail", integration="gmail", create_if_missing=True)
    assistant = noclick.Agent.from_name(
        "assistant",
        create_if_missing=True,
        instructions="You read the user's inbox and email them a summary each morning.",
        tools=[
            gmail.only("fetch_emails_from_inbox"),
            gmail.only("send_email_message").bind(to="{{user.email}}"),
        ],
    )
```

```ts
import { Agent, Connection, asUser } from "noclick";

await asUser("user_42", async () => {
  const gmail = Connection.fromName("gmail", { integration: "gmail", createIfMissing: true });
  const assistant = Agent.fromName("assistant", {
    createIfMissing: true,
    instructions: "You read the user's inbox and email them a summary each morning.",
    tools: [
      gmail.only("fetch_emails_from_inbox"),
      gmail.only("send_email_message").bind({ to: "{{user.email}}" }),
    ],
  });
});
```

A value is fixed (`channel="#support"`), or names the user the call acts for: `{{user.id}}`, `{{user.email}}`, `{{user.name}}` or `{{user.metadata.<key>}}`, from the [user](https://www.noclick.com/docs/guide/users.md) record. Anything else in `{{...}}` raises `ValueError` before anything is sent. What holds:

- **A bound value always wins**, over what the model passes through in an operation's free-form parameters too (a bound key in an object the operation passes on as is, like Stripe's `extra_params`, is dropped).
- **A tool whose binding can't be filled isn't offered** that turn: a user with no email gets no `send_email_message`, and an account conversation has no `{{user...}}` at all.
- **Policy judges the final arguments**, bound ones included, so a [rule's condition](https://www.noclick.com/docs/guide/policy.md#rules-with-conditions) sees `args.to` as it will be sent.
- **It works wherever tools do**: an agent's `tools`, a [toolkit](https://www.noclick.com/docs/guide/toolkits.md) (which sends its entries with each call) and a [hosted MCP server](https://www.noclick.com/docs/guide/mcp-servers.md), whose `{{user...}}` is the server's user, so an account server doesn't serve a tool bound to one. A shared connection binds the same way: `team_slack.only("send_message_to_channel").bind(channel="#announcements")`.

Every operation you list must take each parameter you bind (else `noclick.InvalidRequest`); `bind` again to add more. A bound operation is that operation's only entry: listing `gmail` (every operation, unbound) beside `gmail.only("send_email_message").bind(...)` raises `noclick.InvalidRequest`, so list the others one by one. On the wire each is `{"tool": "gmail.send_email_message", "bind": {"to": "{{user.email}}"}}`, and an agent's `tools` reads it back that way. [Databases](https://www.noclick.com/docs/guide/databases.md#use-it-from-an-app-or-an-agent) and [buckets](https://www.noclick.com/docs/guide/storage.md#use-it-from-an-app-or-an-agent) bind their operations the same way, to pin an agent to one table or one folder.

A repository on a git host (a `github` connection) can also be checked out in an agent's workspace, with pushes limited to the branches you name: see [Work in a repo from an agent](https://www.noclick.com/docs/guide/repos.md#work-in-a-repo-from-an-agent).

## See what a user has connected

```python
with noclick.as_user("user_42"):
    for connection in noclick.Connection.list():
        print(connection.name, connection.integration, connection.status)
```

```ts
import { Connection, asUser } from "noclick";

await asUser("user_42", async () => {
  for (const connection of await Connection.list()) {
    console.log(connection.name, connection.integration, connection.status);
  }
});
```

Outside `as_user`, `noclick.Connection.list()` lists your account's own connections. To read every user's at once, pass `user_filter=noclick.ALL_USERS`; `integration="gmail"` narrows the list. `noclick.Connection.get` takes an id or a name.

A user's connections are private to them. They don't show up among your own connections in the NoClick app.

## Accounts connected in the app

The accounts you connected in the NoClick app are connections too, so everything your account can use is one list. Outside `as_user`, `noclick.Connection.list()` ends with them, after your named connections: each one's `origin` is `"app"` (a named connection's is `"api"`), its `name` is the one it has in the app, and its id is `credential:` followed by its id, which is how you refer to it:

```python
for connection in noclick.Connection.list(origin="app"):
    print(connection.id, connection.name, connection.integration, connection.access)

slack = noclick.Connection.from_id("credential:9b2a1c5e-7d9f-4a31-8f6d-3f1d2c4b8a7e")
slack.run("send_message_to_channel", {"channel": "#ops", "text": "Deployed."})
noclick.run("credential:9b2a1c5e-7d9f-4a31-8f6d-3f1d2c4b8a7e.list_channels")
```

```ts
import { Connection, run } from "noclick";

for (const connection of await Connection.list({ origin: "app" })) {
  console.log(connection.id, connection.name, connection.integration, connection.access);
}

const slack = Connection.fromId("credential:9b2a1c5e-7d9f-4a31-8f6d-3f1d2c4b8a7e");
await slack.run("send_message_to_channel", { channel: "#ops", text: "Deployed." });
await run("credential:9b2a1c5e-7d9f-4a31-8f6d-3f1d2c4b8a7e.list_channels");
```

They run, look up, verify and [require approval](https://www.noclick.com/docs/guide/connections.md#require-approval-for-an-operation) like any connection, billed and recorded the same way. The app connects and reconnects them, so `connect_link` and `import_` on one raise `noclick.InvalidRequest`; `delete` removes one as the app does (its webhooks come down and the provider revokes it where it can), and only one your account connected: one shared with it raises `noclick.PermissionDenied`. The bare id the app shows reads it too (`GET /v1/connections/<id>`). An account a teammate shared with yours is listed too, with `access` `"view"` or `"edit"` (`"owner"` for your own): it runs, but its `token()` and its approval rules stay its owner's. An account signed in to an app whose sign-in NoClick has since closed to new connections (while the app's provider reviews it, as Pipedrive's and Zendesk's are) is still that app's connection and runs; new ones connect with the ways its integration's `credentials` list. A Claude or ChatGPT plan you signed in to in the app is listed as yours, and an account agent thinks with it by its id (`model_connection="credential:<id>"`); a plan is one person's own, so one a teammate shared with you, or one someone else filled in for you, isn't listed. They belong to your account, never to one of your users: a call made with `as_user` doesn't see them.

An account agent takes one as a tool, the `Connection` itself or its id in `tools`, whole or one operation at a time:

```python
slack = noclick.Connection.from_id("credential:9b2a1c5e-7d9f-4a31-8f6d-3f1d2c4b8a7e")
ops = noclick.Agent.from_name(
    "ops",
    create_if_missing=True,
    instructions="You post deploy notes for the team.",
    tools=[slack.only("send_message_to_channel"), "credential:9b2a1c5e-7d9f-4a31-8f6d-3f1d2c4b8a7e.list_channels"],
)
```

```ts
import { Agent, Connection } from "noclick";

const slack = Connection.fromId("credential:9b2a1c5e-7d9f-4a31-8f6d-3f1d2c4b8a7e");
const ops = Agent.fromName("ops", {
  createIfMissing: true,
  instructions: "You post deploy notes for the team.",
  tools: [slack.only("send_message_to_channel"), "credential:9b2a1c5e-7d9f-4a31-8f6d-3f1d2c4b8a7e.list_channels"],
});
```

Each turn checks it again: once it's removed in the app or no longer shared with your account, its tools tell the agent they can't run, and once it's disconnected, that it needs reconnecting in the app. A user's agent can't take one, and a [toolkit](https://www.noclick.com/docs/guide/toolkits.md) names connections only, since its tools go on the wire by a connection's name.

An account agent's `OnEvent` takes one as its connection too, so a WhatsApp linked in the app wakes the agent on each message: `noclick.OnEvent(whatsapp, "receive_message")`.

### Accounts shared with a team

An account a teammate shared with a team workspace you're in is that team's to use, in its workspace only. Name the workspace by its id (`organization_id`, `organizationId` in TypeScript) and it's listed, found and run there:

```python
for connection in noclick.Connection.list(organization_id="5c0d9e4a-7b1f-4e2a-9c3d-8f6b2a1e4d70"):
    print(connection.name, connection.access, connection.organization_id)

docs = noclick.Connection.from_id("credential:3e7a1c5e-7d9f-4a31-8f6d-3f1d2c4b8a7e", organization_id="5c0d9e4a-7b1f-4e2a-9c3d-8f6b2a1e4d70")
docs.run("list_documents")
```

```ts
import { Connection } from "noclick";

const team = "5c0d9e4a-7b1f-4e2a-9c3d-8f6b2a1e4d70";
for (const connection of await Connection.list({ organizationId: team })) {
  console.log(connection.name, connection.access, connection.organizationId);
}
await Connection.fromId("credential:3e7a1c5e-7d9f-4a31-8f6d-3f1d2c4b8a7e", { organizationId: team }).run("list_documents");
```

A connection read in a team workspace carries it (`organization_id`), and everything it does goes there: a run is the team's work, billed as the app bills that team's. Your own accounts read there run there too. Without `organization_id` (or with your own workspace's), a team's account isn't listed and its id finds nothing. An agent's tools, `noclick.run` and a call `as_user` stay in your account's own workspace, and an app's code names no team workspace (`noclick.PermissionDenied`). Leave the team and its accounts are gone.

## Require approval for an operation

A connection can require its owner to approve each call of an operation, wherever the account is used: your code, your agents, and the workflows in the app. `require_approval` adds operations, or `"*"` for every one, and never removes any; lifting one is done in the app:

```python
gmail = noclick.Connection.from_name("gmail")
gmail.require_approval("send_email_message", "delete_message")
print(gmail.approval_operations)   # ['delete_message', 'send_email_message']
```

```ts
import { Connection } from "noclick";

const gmail = Connection.fromName("gmail");
await gmail.requireApproval("send_email_message", "delete_message");
console.log(gmail.approvalOperations);   // ['delete_message', 'send_email_message']
```

It needs an account to hold the rules: on a pending connection it raises `noclick.InvalidRequest`, so connect it first. A held call raises `noclick.ApprovalRequired`, as a [policy](https://www.noclick.com/docs/guide/policy.md) hold does, and runs once its owner approves that exact call. Use a policy for rules about tools across your account; use this for one connected account that should never act unseen, whoever uses it.

## From an app's preview

An app's [preview](https://www.noclick.com/docs/guide/apps.md#preview-a-branch) only reads through its connections. An operation that may write in the account (anything not named as a read, such as `list_`, `get_` or `search_`) raises `noclick.PermissionDenied`, naming the fix, so trying a branch never posts to a real channel or emails a real customer. Operations that run on NoClick's key act in no account of yours and run as usual. Production is unchanged.

When a connection holds a test account (a sandbox workspace, a test inbox), mark it, and previews write through it as production does:

```python
slack = noclick.Connection.from_name("slack-sandbox")
slack.mark_test_account()
print(slack.test_account)   # True
```

```ts
import { Connection } from "noclick";

const slack = Connection.fromName("slack-sandbox");
await slack.markTestAccount();
console.log(slack.testAccount);   // true
```

`mark_test_account(False)` takes the mark back. Only the account that connected it marks it, and only once it holds an account.

## Check that it works

`status` is `pending` until an account is connected, `connected` after, and `disconnected` once the account is revoked or its credential deleted. A pending connection still runs its [operations on NoClick's key](https://www.noclick.com/docs/guide/integrations.md#operations-on-noclick-s-key). A connected account can still fail (a revoked grant, a key for the wrong workspace), so `verify()` asks the provider now:

```python
check = gmail.verify()
print(check.reachable, check.message)   # True  Signed in as ana@example.com.
```

```ts
const check = await gmail.verify();
console.log(check?.reachable, check?.message);   // true  Signed in as ana@example.com.
```

`reachable` is `True` when the provider accepted the account, `False` when it refused it, and `None` when NoClick can't tell. `samples` holds a few things from the account, such as channel or repository names, and `message` says what was found. The result is also kept as `gmail.verification`, which stays `None` for a connection nobody has checked yet. There's nothing to ask about without an account: `verify()` on a pending connection raises `noclick.NeedsConnection`, and on a disconnected one `noclick.CredentialDisconnected`, each with the `connect_url` that fixes it (a connection of another scope's, say the account's from a user's code, raises `noclick.NotAvailable`).

## Reconnect

A disconnected connection keeps its name. Send a new link, and once the user connects, the connection holds the new account and NoClick removes the old one. Everything that names the connection keeps working:

```python
if gmail.refresh().status == "disconnected":
    gmail.request(reason="Gmail stopped working. Reconnect it to keep your summaries coming.")
```

```ts
if ((await gmail.refresh()).status === "disconnected") {
  await gmail.request({ reason: "Gmail stopped working. Reconnect it to keep your summaries coming." });
}
```

A run through a disconnected connection raises `noclick.CredentialDisconnected`, which carries the reconnect link as `connect_url`.

## Bring credentials you already hold

If you already have a user's API key or OAuth tokens, create the connection with them. NoClick validates the fields and probes the provider before saving, so a rejected key leaves nothing behind:

```python
crm = noclick.Connection.from_name(
    "crm",
    integration="affinity",
    data={"api_key": "..."},
    create_if_missing=True,
    user="user_42",
)
```

```ts
import { Connection } from "noclick";

const crm = Connection.fromName("crm", {
  integration: "affinity",
  data: { api_key: "..." },
  createIfMissing: true,
  user: "user_42",
});
```

Like any `from_name`, this creates the connection holding that key the first time and uses the existing one after (it never overwrites a key). `noclick.Connection.create(..., data=...)` always creates (with `allow_existing=True`, a taken name returns that connection and its key stays). `import_` swaps in a new key later, a rotated key for example: `crm.import_({"api_key": "..."})`. When a service takes more than one kind of credential, `credential_type=` says which one you hold; [`Connection.integrations`](https://www.noclick.com/docs/reference/python/Connection.md#Connection.integrations) lists the types each integration accepts as `credential_types`, and `GET /v1/integrations/{name}` lists, for each one, the `fields` its `data` takes: each field's name, whether it's required and whether it's secret.

## WhatsApp

Only a WhatsApp connection linked by QR code (`whatsapp_qr`) receives messages: an `OnEvent` trigger on `receive_message` wakes the agent for each message that arrives. A key (`whatsapp_access_token`) connects a number on Meta's WhatsApp Business Platform, the API a business sets up in a Meta developer app (a phone number ID and an access token). It sends, templates included, and manages the business profile, but NoClick reads no chats and wakes no agent through it.

The QR connection is a linked device on the person's own WhatsApp account. Its connect page shows a code, and the person scans it on the phone with that number, in WhatsApp under Linked devices → Link a device, as they would to open WhatsApp Web. It works the same with the WhatsApp and the WhatsApp Business app, keeps the number they already use, and leaves WhatsApp working on their phone. NoClick isn't told which app it is, or whether the account is a person's or a business's, so nothing about the connection says either. For the number, that means:

- The agent reads the account's chats and sends as it. Its replies come from that number and show on the phone too, as messages sent from WhatsApp Web do.
- WhatsApp decides how long the link lasts. It logs linked devices out when the phone goes unused for a long while, and the person can log NoClick out under Linked devices at any time. Messages stop reaching the agent until the phone is linked again. Link it again on the same connection rather than making a new one each time: fresh links stacked on one phone have all been logged out at once.
- WhatsApp's own terms govern the account, however it's used. NoClick doesn't know how WhatsApp treats an account whose messages an agent answers through a linked device, and has no say in what WhatsApp does with a number. Weigh that for a number a business depends on. The Business Platform is Meta's own way for a business to automate its messages, and on it NoClick sends but doesn't receive.

## Telegram

A Telegram connection (`telegram_bot_token`) holds a bot's token, which its owner gets from @BotFather. Through it an agent sends as the bot, and an `OnEvent` trigger on `receive_webhook_messages` wakes the agent for each update the bot gets: a message in a private chat, a group or a channel, an edit, a button press. Each chat is its own conversation, and a photo, file or voice note sent to the bot comes with its message.

NoClick hears the bot by pointing its webhook at NoClick, with a secret Telegram sends back on every delivery. Telegram gives a bot one webhook, so a bot wakes one trigger: a second trigger on the same bot takes nothing from the first, and its `status` is `error`, with `error` naming the one that has the bot. While the trigger is on, code of yours that set the bot's webhook elsewhere, or reads `getUpdates`, gets no updates. Removing the trigger clears the bot's webhook, unless it points somewhere else by then.

## Model providers

A model provider's connection holds what an agent on a [coding harness](https://www.noclick.com/docs/guide/agents.md#harnesses) thinks with: an API key, or a Claude or ChatGPT plan. It's a connection like any other, of an integration whose `kind` is `"model"` (`anthropic`, `openai`, `openrouter`, `opencode` and more): `noclick.Connection.integrations(kind="model")` lists them. The agent names it as its `model_connection`, never in its `tools`.

```python
claude = noclick.Connection.create("claude", integration="anthropic", data={"api_key": "sk-ant-..."})
print(claude.verification)   # Anthropic accepted the key
```

```ts
import { Connection } from "noclick";

const claude = await Connection.create("claude", { integration: "anthropic", data: { api_key: "sk-ant-..." } });
console.log(claude.verification);   // Anthropic accepted the key
```

`data={"api_key": ...}` holds your key, probed first like any key. Without `data`, the connection is pending and its link asks for the key. Where the provider's `subscription` is true, the link also offers signing in with a plan instead, on your account's connection as on a user's: a Claude plan runs only `claude_code`, and a ChatGPT plan runs `codex`, `opencode`, `hermes` and `openclaw` on the models the plan allows. A plan connects only by signing in, by the person it belongs to: at the link, or, for your account, in the NoClick app ([accounts connected in the app](https://www.noclick.com/docs/guide/connections.md#accounts-connected-in-the-app)). A connection holding one is never shared with another scope's agent. Whether a plan fits is yours to judge ([when a plan fits](https://www.noclick.com/docs/guide/connections.md#when-a-plan-fits)):

```python
with noclick.as_user("user_42"):
    plan = noclick.Connection.from_name("claude", integration="anthropic", create_if_missing=True)
    print(plan.connect_url)   # "Paste a Claude key" or "Sign in with Claude"
```

```ts
import { Connection, asUser } from "noclick";

await asUser("user_42", async () => {
  const plan = await Connection.fromName("claude", { integration: "anthropic", createIfMissing: true }).hydrate();
  console.log(plan.connectUrl);   // "Paste a Claude key" or "Sign in with Claude"
});
```

NoClick never hands out a model key or plan token: `token()` on a model provider's connection raises `noclick.PermissionDenied`.

> [!NOTE]
> Invite-only beta. [Request access](mailto:support@noclick.com?subject=Invite-only%20beta%20access) to use it; without access, a call answers 404.

A user's agent can think with your account's key: pass the account's `Connection` object as its `model_connection`, as you would [share one in its tools](https://www.noclick.com/docs/guide/connections.md#share-one-across-users). The same rules hold: only a key that acts for your whole account can set it, and a connection holding someone's plan is never shared, so a user's agent runs on your key or its user's own plan, never on another person's. The model calls are paid on that key; NoClick bills the agent's user for the rest of the turn.

```python
import noclick

claude = noclick.Connection.from_name("claude")   # your account's Claude key
with noclick.as_user("user_42"):
    coder = noclick.Agent.from_name(
        "coder", create_if_missing=True, instructions="You fix the user's site.",
        harness="claude_code", model_connection=claude,
    )
```

```ts
import { Agent, Connection, asUser } from "noclick";

const claude = Connection.fromName("claude");   // your account's Claude key
await asUser("user_42", async () => {
  const coder = Agent.fromName("coder", {
    createIfMissing: true, instructions: "You fix the user's site.",
    harness: "claude_code", modelConnection: claude,
  });
});
```

### When a plan fits

A Claude or ChatGPT plan is one person's own subscription, so it suits agents that work for that person: your own assistant or coding agent, or an agent answering your own business's messages, on your account's connection; a user's agent on that user's plan, in their scope. Use an API key instead when the agent serves your product's many users, when the plan belongs to someone other than the person the agent works for, or when the provider's terms for that plan wouldn't cover the use. NoClick doesn't decide this for you: an agent runs on whatever its connection holds. An agent setting one up for someone says which fits and why, and goes with their choice.

## Call the provider yourself

To call a provider's API directly with a user's OAuth connection, get a short-lived access token. This needs a key with the `credentials:token` scope:

```python
token = gmail.token()
headers = {"Authorization": f"{token.token_type} {token.access_token}"}
```

```ts
const token = await gmail.token();
const headers = { Authorization: `${token.tokenType} ${token.accessToken}` };
```

You get access tokens only, never refresh tokens or stored API keys. For API-key connections, use [operations](https://www.noclick.com/docs/guide/integrations.md) instead. Like `verify()`, it needs an account: a pending connection raises `noclick.NeedsConnection` and a disconnected one `noclick.CredentialDisconnected`, each with its `connect_url`.

## Delete

```python
gmail.delete()
```

```ts
await gmail.delete();
```

This deletes the connection and, where the provider supports it, disconnects NoClick from the account. Code and agents that name it stop working until a connection with that name exists again, and any agent it was [granted](https://www.noclick.com/docs/guide/grants.md) to loses its tools.

`used_by` says beforehand what loses it: the agents holding it (in their `tools`, as their `model_connection`, or [granted](https://www.noclick.com/docs/guide/grants.md) it by their user), the [hosted MCP servers](https://www.noclick.com/docs/guide/mcp-servers.md) with it in their tools, and the [apps](https://www.noclick.com/docs/guide/apps.md) that bind it, each with its `kind` (`agent`, `mcp_server` or `project`), `id`, `name`, `user_id` and an app's `binding` name:

```python
gmail = noclick.Connection.from_name("gmail", user="user_42")
for holder in gmail.used_by:
    print(holder["kind"], holder["name"])
gmail.delete()
```

```ts
import { Connection } from "noclick";

const gmail = await Connection.fromName("gmail", { user: "user_42" }).hydrate();
for (const holder of gmail.usedBy) {
  console.log(holder.kind, holder.name);
}
await gmail.delete();
```
