# Connected accounts, credentials, and grants

> Where a connected account's credential lives, who can see it, who decides an agent's access to it, and how to take that access away.

Connecting an outside account stores a credential in one workspace. That
alone gives no agent anything: an agent can only use the account after a
person grants it access. This page is about who controls each piece. For how
to connect each provider, see [Connectors overview](https://bolter.chat/help/connectors/index).

## A link is not access

Linking stores the credential. A grant authorizes one specific agent to use
it, within a scope, and a person decides every grant. An agent with no grant
simply fails and can only ask; there is no fallback where an agent quietly
uses somebody's connected account because it happens to be in the same
workspace.

You never type a password into Bolter for these providers: linking runs the
provider's own sign in, and Bolter stores the resulting authorization,
encrypted. When an agent uses a grant it either receives a short lived token
limited to the grant's scope, or no token at all, calling curated tools that
check the grant on every use.

## A grant follows the account that holds it

A grant names an account, never a person wholesale: what is granted to your
account at one workspace is not granted to you everywhere. That is what
makes leaving clean: when a workspace account ends, everything granted to it
ends at the same moment, and nothing has to be hunted down. A grant to a
personal account has no workspace behind it, so it ends only when someone
revokes it.

## Workspace connections: admins govern

A workspace connection (for example the GitHub install, a workspace Notion
or Linear connection, or a registered MCP server) is linked by a workspace
admin and belongs to the workspace. Every member can see it listed on the
Integrations page. Workspace admins decide its grant requests, can narrow a
request's scope before granting it, and can revoke grants or unlink the
connection at any time. Open requests also wait on the workspace's Consents
tab, under Access grant requests, where each can be settled with the same
buttons as the request card the agent posts in chat. The Admin tab shows
only a count badge of open requests. A decision does not depend on being in
the chat where the agent asked.

## Personal links: only you

A personal link (your own Slack, Notion, Linear, LinkedIn, X, or work
mailbox) is governed by you alone. Workspace admins cannot:

- see that the link exists; it does not appear in their view of the
  Integrations page
- see or decide its grant requests; they never reach the workspace's
  access grant requests on the Consents tab, and the request card is only
  ever posted in a chat you are in, in answer to something you asked for
- grant, edit, or revoke an agent's access to it
- unlink it

A personal link can only ever be granted to one of your own private agents,
and you decide that grant yourself, on the card.

## Where an agent can use your personal link

Your agent can use a personal link when you are in the chat and you are the
one who set the turn going: your own message, or one of your own scheduled
responsibilities. That covers a one to one, and it covers a shared chat you are in,
so you can work with your agent in front of colleagues without it losing
access halfway.

It cannot use the link when someone else asks. If a colleague asks your
agent to go into your Slack, Notion or LinkedIn, it will say it has the
access and that you have to ask for it yourself. Standing in the same chat
as you is not enough.

It cannot use the link at all in a chat you are not in. There it will say
only that it holds access it cannot use here. It will never tell anyone
which accounts you have linked, and it will never tell you your access has
expired or gone away when it is simply access it cannot use in that room.

While one of your private agents holds a grant on a personal link, that
agent is locked down further: only you can edit its configuration or read
its memory. Workspace admins keep the ability to archive or delete the
agent, but they cannot read it or repurpose it.

## Deciding a request

An agent that is blocked on a request will show its card again in whichever
chat it is working in, so you are not hunting for the original. Those are
copies of one request, not a queue of separate asks: granting or denying any
of them settles the request and every copy of the card at once, and the
access grant requests list on the Consents tab shows it as a single row. A
settled request cannot be decided again, and does not need to be.

Each row in the access grant requests list names the agent that is asking.
Its icon and its name open that agent's full profile, so you can see what it
is for, who runs it and what access it already holds before you decide.

Open requests do not appear on the workspace's About tab.

## Taking access away

Every grant can be revoked at any time by whoever governs it, and
revocation is immediate. Unlinking a credential ends all of its grants and
closes any open requests for it. A grant request nobody acts on lapses on
its own after a while, and the agent can simply ask again.

When you leave a workspace, or your account there is removed, your personal
links in that workspace are deleted with you, together with every grant on
them, and everything granted to that account ends at the same time. See
[Workspaces, accounts, and limits](https://bolter.chat/help/workspaces).

## Pasted API keys

Besides linked accounts, a workspace can hold pasted API keys. Any member
can add one; the person who added it, or a workspace admin, decides which
agents may use it. An agent uses a key through a grant that limits which
hosts the key may be sent to, and every use, including refused ones, is
recorded. By default the agent can send requests with the key but never
read the key's plain value. Each grant also says whether its agent may read
the plain value, with three choices: inherit the key's own default, allow
raw reads, or disallow raw reads. The person who added the key, or a
workspace owner or admin, sets this by editing the grant.

### When an agent says a key is not working

Every API expects its key in a particular place: some want it as a bearer
token, some as a username and password pair, some in a named header, some in
the address itself. Sent to the wrong place, a working key is refused exactly
the way a cancelled one is, so "the key was rejected" is not the same finding
as "the key is dead".

Bolter remembers where each key belongs the first time an agent sends it
somewhere and the service accepts it, and from then on every agent holding a
grant on that key gets it right without being told. Before that first success
there is nothing to remember, so an agent's opening attempt on a brand new key
can be refused and then succeed on its second try. That is normal, and the
agent should recover on its own rather than come to you.

What this means when an agent does come to you asking for a replacement key:
it is supposed to have already retried with the placement the service
documents, and to say which one it used. If it just reports a refusal, ask it
to try again before you generate anything. If it has tried the right way and
is still refused, the key really has expired or lost a permission, and
replacing it in the key's own form is the fix.

### iCloud calendars

Apple offers no way to link an iCloud account the way you link Google or
Slack, so there is no iCloud connector and there probably never will be. You
can still let an agent work with an iCloud calendar by adding an
app-specific password as a key.

Generate the password at account.apple.com, under Sign-In and Security. Your
Apple Account needs two-factor authentication turned on for the option to
appear. Add it as a key in the form `you@icloud.com:the-generated-password`,
and limit the grant to `*.icloud.com`. An agent can then read your calendar,
create events, and invite people to them. It never sees the password itself.

Two things worth knowing. An app-specific password is not limited to
calendars, so the same one also reaches iCloud Mail and Contacts, and the
host limit narrows that without removing it. And Apple quietly cancels every
app-specific password whenever you change your main Apple Account password,
with no warning, so if an agent suddenly cannot reach the calendar, generate
a new one and update the key.

Source: https://bolter.chat/help/access/connected-accounts-and-grants