Agent Access: Grant Credentials to Agents

Agents don’t share a credential pool. Each agent uses exactly the credentials you grant it: an app connection (optionally narrowed to specific tools), or a secret. Everything else stays invisible — the gateway injects nothing an agent wasn’t granted.

How access works

A project holds the credential pool: secrets, LLM keys, and app connections (including ones shared from the organization). A grant attaches one credential from that pool to one agent.

No grant, no access. A new agent starts with no grants. Until you attach something, the gateway injects no credentials for it, and its container config carries no credential stubs.
Grants take effect immediately. There is no draft or publish step — the moment an attach or detach returns, the gateway enforces it.
Connections can be narrowed per tool. A connection grant is either full access (every tool the app supports, including tools the provider adds later) or custom — you name which tools run freely and which pause for human approval; everything unnamed is blocked.
Secrets are all-or-nothing. A secret grant has no tool lists — the agent can use the credential wherever its host pattern matches.

Granting access

Dashboard
CLI

Open Agents, pick the agent, and use its access list to attach connections and secrets. Each app connection row has a Manage action where you switch between full and per-tool access.You can also start from the credential: open an app under Apps, choose the connection’s Agent access, and toggle agents on or off there. Both views write the same grants.

Attach a connection with full access:

onecli agents grants attach-connection --id agent_abc123 --connection-id conn_9f2c1b

{
  "agentId": "agent_abc123",
  "mode": "grants",
  "connections": [
    {
      "connectionId": "conn_9f2c1b",
      "provider": "gmail",
      "label": "Support inbox",
      "scope": "project",
      "access": "full",
      "allow": [],
      "ask": []
    }
  ],
  "secrets": []
}

Attach a secret or LLM key:

onecli agents grants attach-secret --id agent_abc123 --secret-id sec_5e8c02

{
  "agentId": "agent_abc123",
  "mode": "grants",
  "connections": [
    {
      "connectionId": "conn_9f2c1b",
      "provider": "gmail",
      "label": "Support inbox",
      "scope": "project",
      "access": "full",
      "allow": [],
      "ask": []
    }
  ],
  "secrets": [
    {
      "secretId": "sec_5e8c02",
      "name": "ANTHROPIC_KEY",
      "type": "anthropic",
      "scope": "project"
    }
  ]
}

Read an agent’s grants, or detach:

onecli agents grants list --id agent_abc123
onecli agents grants detach-connection --id agent_abc123 --connection-id conn_9f2c1b

{
  "status": "detached",
  "agentId": "agent_abc123",
  "connectionId": "conn_9f2c1b"
}

List every agent with a summary of what’s attached:

onecli agents list --with-grants

Per-tool access

For apps with a tool catalog (Gmail, GitHub, Notion, and most others), a connection grant can name tools instead of granting the whole app. Each tool is in one of three states:

Allow — the agent calls it freely.
Ask — every call pauses for manual approval.
Never — the tool is blocked. Any tool you don’t name is blocked.

In the dashboard, the Manage dialog on a connection row presents exactly this tri-state per tool. From the CLI, pass tool ids (from onecli apps permission-definition --provider gmail):

onecli agents grants attach-connection --id agent_abc123 --connection-id conn_9f2c1b \
  --allow search_messages,get_message --ask send_email

{
  "agentId": "agent_abc123",
  "mode": "grants",
  "connections": [
    {
      "connectionId": "conn_9f2c1b",
      "provider": "gmail",
      "label": "Support inbox",
      "scope": "project",
      "access": "custom",
      "allow": ["search_messages", "get_message"],
      "ask": ["send_email"]
    }
  ],
  "secrets": []
}

Two constraints apply to custom grants:

At least one tool must be allowed or set to ask. A grant with every tool on Never is not a grant — detach the connection instead. The API answers 422 with Custom access needs at least one allowed or approval tool — detach instead.
A tool can’t be both allowed and require approval. The same id in both lists is rejected: A tool can't be both always-allowed and require approval.

Full access includes tools the provider adds to the catalog later; a custom grant doesn’t — new tools arrive blocked until you allow them.

The Ask state requires a plan with manual approvals. Attaching and the allow/never states work on every plan; setting a non-empty ask list without the feature returns 403.

After connecting an app

When you finish an OAuth connect from the dashboard, the app page opens the new connection’s Agent access dialog so you can grant agents in the same motion. A freshly connected account has no grants yet — until you toggle agents on, nothing can use it. The same applies over the API: POST /v1/apps/{provider}/connect returns a connection object only when a brand-new connection was created. Follow it with a grant call for each agent that should use it.

The organization ceiling

Organization policy rules cap what any project grant can allow. A grant is the project-level intent; the organization level can still force approval or block a tool outright, and the strictest answer wins. In the per-tool dialog, rows the organization locks are marked and can’t be loosened from the project — an org-blocked tool stays blocked no matter what the grant says. The API reflects this as orgCeiling on each tool in GET /v1/policy/effective-app-permissions: what the organization level alone would decide, independent of your grant.

Granted vs effective

Grants are what you intend; effective access is what actually happens after organization rules apply. Three read-only reflections answer “what can this agent really do”:

Question	Endpoint
Which credentials can this agent actually use?	`GET /v1/agents/{agentId}/effective-credentials`
Which agents can really reach this connection?	`GET /v1/connections/{connectionId}/effective-agents`
What can agents do with this app, per tool?	`GET /v1/policy/effective-app-permissions?provider=gmail`

When a request is blocked and the grant looks right, check the effective view first — an organization rule may be deciding. The CLI’s onecli agents credentials and onecli apps connections agent-access commands read these same reflections.

Multiple accounts of one app

You can connect several accounts of the same app (two Gmail inboxes, a personal and an org GitHub) and grant an agent any subset. Each account is its own connection with its own grant and its own per-tool lists. When a request could be served by more than one granted account, the gateway answers 409 and asks the agent to name one with the x-onecli-connection-id header. See Multiple accounts for the full protocol.

API quick reference

All grant routes require a project context (X-Project-Id with an organization key). Writes return the agent’s updated grant set; detaches return 204.

Operation	Endpoint
Read an agent’s grants	`GET /v1/agents/{agentId}/grants`
Attach / rewrite a connection grant	`PUT /v1/agents/{agentId}/grants/connections/{connectionId}`
Detach a connection	`DELETE /v1/agents/{agentId}/grants/connections/{connectionId}`
Attach a secret	`PUT /v1/agents/{agentId}/grants/secrets/{secretId}` (no body)
Detach a secret	`DELETE /v1/agents/{agentId}/grants/secrets/{secretId}`
Read a connection’s granted agents	`GET /v1/connections/{connectionId}/grants`
Grant / revoke from the connection side	`PUT` / `DELETE /v1/connections/{connectionId}/grants/agents/{agentId}`
List agents with grant summaries	`GET /v1/agents?include=grants-summary`

Next steps

Policy rules — organization-wide guardrails on top of grants
Multiple accounts — the gateway’s account-selection protocol
Projects — how the credential pool is scoped

​How access works

​Granting access

​Per-tool access

​After connecting an app

​The organization ceiling

​Granted vs effective

​Multiple accounts of one app

​API quick reference

​Next steps

How access works

Granting access

Per-tool access

After connecting an app

The organization ceiling

Granted vs effective

Multiple accounts of one app

API quick reference

Next steps