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
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/...A user 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.
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:
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)A toolkit or agent given both gets both sets of tools and picks per call.
Wait for the user
gmail.wait() # returns once an account is connected
print(gmail.account) # ana@example.com: the account it reachesaccount 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.
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 reasonLinks 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: link.wait() returns the connected Connection.
Use it
gmail.run("send_email_message", {
"to": ["ana@example.com"],
"subject": "Your weekly summary",
"body": "Three invoices were paid this week.",
})Calling integrations covers what a connection can do (operations() and operation()), run and lookup. To hand a connection to a model, list it in a toolkit or in an agent's tools. 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.
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")],
)"gmail" is Dana's own connection; team_slack stays Acme's. Your account's own connections share the same way:
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"],
)What holds when you share one:
- Only your account decides. Only a key that acts for your whole account (the
NoClick-Userheader 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'smodel_connection. A key pinned to a user, a session, an app's code or an agent's own NoClick tools raisesnoclick.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, liketeam-slack. - The owner approves. A call is judged by your account's approval rules 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_byon 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.
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.
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}}"),
],
)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 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 sees
args.toas it will be sent. - It works wherever tools do: an agent's
tools, a toolkit (which sends its entries with each call) and a hosted MCP server, 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 and buckets 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.
See what a user has connected
with noclick.as_user("user_42"):
for connection in noclick.Connection.list():
print(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:
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")They run, look up, verify and require approval 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:
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"],
)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 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:
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")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:
gmail = noclick.Connection.from_name("gmail")
gmail.require_approval("send_email_message", "delete_message")
print(gmail.approval_operations) # ['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 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 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:
slack = noclick.Connection.from_name("slack-sandbox")
slack.mark_test_account()
print(slack.test_account) # Truemark_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. A connected account can still fail (a revoked grant, a key for the wrong workspace), so verify() asks the provider now:
check = gmail.verify()
print(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:
if gmail.refresh().status == "disconnected":
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:
crm = noclick.Connection.from_name(
"crm",
integration="affinity",
data={"api_key": "..."},
create_if_missing=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 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.
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 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.
claude = noclick.Connection.create("claude", integration="anthropic", data={"api_key": "sk-ant-..."})
print(claude.verification) # Anthropic accepted the keydata={"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). A connection holding one is never shared with another scope's agent. Whether a plan fits is yours to judge (when a plan fits):
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"NoClick never hands out a model key or plan token: token() on a model provider's connection raises noclick.PermissionDenied.
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. 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.
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,
)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:
token = gmail.token()
headers = {"Authorization": f"{token.token_type} {token.access_token}"}You get access tokens only, never refresh tokens or stored API keys. For API-key connections, use operations 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
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 to loses its tools.
used_by says beforehand what loses it: the agents holding it (in their tools, as their model_connection, or granted it by their user), the hosted MCP servers with it in their tools, and the apps that bind it, each with its kind (agent, mcp_server or project), id, name, user_id and an app's binding name:
gmail = noclick.Connection.from_name("gmail", user="user_42")
for holder in gmail.used_by:
print(holder["kind"], holder["name"])
gmail.delete()