> ## Documentation Index > Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt > Use this file to discover all available pages before exploring further. # Attach a secret to an agent > Attach a secret (an API key or LLM key) to an agent. Secrets are all-or-nothing — there are no per-tool lists, so the request takes **no body**. ## OpenAPI ````yaml /openapi.yaml put /agents/{agentId}/grants/secrets/{secretId} openapi: 3.1.0 info: title: OneCLI API version: '1.0' description: > The OneCLI API lets you manage agents, their credential grants, secrets, app connections, organization policy rules, and user settings programmatically. Per-agent access is managed with **grants** (attach an app connection or secret to an agent, optionally naming per-tool allow/approval lists). Organization-wide guardrails are **policy rules** under `/org/policy`. The project `/policy` endpoints are read-only reflections of the enforced result. **Base URL:** `https://api.onecli.sh/v1` (Cloud) or `http://localhost:10254/v1` (self-hosted) ## Authentication All endpoints require authentication via one of: - **API Key** — `Authorization: Bearer ` header. Generate keys in the dashboard or via `GET /v1/user/api-key`. - **Session** — Cookie-based session from the web dashboard. For organization-scoped API keys, include the `X-Project-Id` header to specify which project to operate on. servers: - url: https://api.onecli.sh/v1 description: OneCLI Cloud - url: http://localhost:10254/v1 description: Self-hosted (Docker) security: - bearerAuth: [] tags: - name: Agents description: Manage agents and their access tokens. - name: Grants description: >- Which credentials each agent may use — attach app connections (with optional per-tool allow/approval lists) and secrets. Writes take effect immediately. - name: Secrets description: Manage credentials that the gateway injects into outbound requests. - name: Policy description: >- Read-only reflection of the enforced project policy, compiled from agent grants plus organization rules. Project access is written through the Grants endpoints; organization rules through Organization Policy. - name: Approvals description: >- Long-poll for pending manual-approval requests and submit approve/deny decisions. - name: User description: Manage your user profile and API keys. - name: Projects description: >- Manage projects within your organization. Requires admin role for create/update and owner role for delete. Cloud only. - name: Team description: Provision team members programmatically. Requires admin role. Cloud only. - name: Apps description: >- Manage app connections (OAuth and direct credentials), BYOC configuration, permission catalogs, and blocklists. - name: Connections description: App connections as a top-level resource. - name: Utility description: Health check and project resource summaries. - name: Agent Setup description: >- Endpoints agents and orchestrators use to bootstrap gateway access (container config, credential stubs, gateway skill). - name: Migration description: Migrate data from a self-hosted instance to OneCLI Cloud. - name: Organization Secrets description: >- Manage secrets at the organization level. Organization secrets apply across all projects. Available on OneCLI Cloud and self-hosted Enterprise. - name: Organization Policy description: >- Author policy-engine rules at the organization level. Organization rules apply across all projects. Available on OneCLI Cloud and self-hosted Enterprise. - name: Organization Connections description: >- Manage app connections at the organization level. Available on OneCLI Cloud and self-hosted Enterprise. - name: Organization App Config description: >- Connect apps (OAuth and direct credentials) and manage BYOC app configuration at the organization level. Available on OneCLI Cloud and self-hosted Enterprise. - name: Organization Approvals description: >- Long-poll for manual-approval requests across every project in the organization. Available on OneCLI Cloud and self-hosted Enterprise. - name: Partner Organizations description: >- Create and manage customer organizations as a partner. Requires a Partner API key. Cloud only. - name: Partner Projects description: Manage projects within an unclaimed partner organization. Cloud only. - name: Partner Secrets description: >- Manage partner-level secrets inherited by every organization you manage. Cloud only. - name: Partner Budgets description: >- Cap how much an organization can spend on a partner LLM key. Owner or admin only. Cloud only. - name: Partner Members description: >- Manage who can sign in to your partner portal. Owner or admin only. Cloud only. - name: Organization Partner description: Inspect and detach an organization's partner relationship. Cloud only. paths: /agents/{agentId}/grants/secrets/{secretId}: put: tags: - Grants summary: Attach a secret to an agent description: > Attach a secret (an API key or LLM key) to an agent. Secrets are all-or-nothing — there are no per-tool lists, so the request takes **no body**. operationId: setAgentSecretGrant parameters: - $ref: '#/components/parameters/agentId' - $ref: '#/components/parameters/secretId' responses: '200': description: The agent's updated grant set content: application/json: schema: $ref: '#/components/schemas/AgentGrants' '404': description: Agent or secret not found content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: agentId: name: agentId in: path required: true schema: type: string secretId: name: secretId in: path required: true schema: type: string schemas: AgentGrants: type: object description: >- An agent's full grant set — returned by grant reads and by every grant write. properties: agentId: type: string mode: type: string enum: - all - grants description: >- Always `grants` on current servers. The `all` value is wire compatibility with older self-hosted releases — never branch behavior on it. connections: type: array items: $ref: '#/components/schemas/AgentGrantConnection' secrets: type: array items: $ref: '#/components/schemas/AgentGrantSecret' Error: description: | Error responses take one of two shapes depending on the failing layer: route-level validation returns the flat shape (`{ "error": "..." }`), while authentication failures (401/403) and service errors (not-found, conflict, and service-level validation) return the envelope (`{ "error": { "message": "...", "type": "..." } }`). oneOf: - $ref: '#/components/schemas/ErrorFlat' - $ref: '#/components/schemas/ErrorEnvelope' AgentGrantConnection: type: object description: One app connection granted to an agent. properties: connectionId: type: string provider: type: string description: App provider, e.g. `gmail`. label: type: string nullable: true description: The connection's label — distinguishes multiple accounts of one app. scope: type: string enum: - project - organization description: >- Where the connection lives. Organization connections are shared into every project. access: type: string enum: - full - custom description: >- `full` = every tool the app supports; `custom` = only the `allow`/`ask` lists below. allow: type: array items: type: string description: Tool ids the agent may call freely. Empty when `access` is `full`. ask: type: array items: type: string description: >- Tool ids that pause for human approval on every call. Empty when `access` is `full`. AgentGrantSecret: type: object description: >- One secret granted to an agent. Secrets are all-or-nothing — no per-tool lists. properties: secretId: type: string name: type: string type: type: string description: '`generic` is a plain secret; `anthropic`/`openai` are LLM keys.' scope: type: string enum: - project - organization ErrorFlat: type: object description: Flat error shape used by route-level validation. properties: error: type: string required: - error ErrorEnvelope: type: object description: >- Envelope error shape used for authentication failures and service errors. properties: error: type: object properties: message: type: string type: type: string description: Error category (e.g. `authentication_error`). securitySchemes: bearerAuth: type: http scheme: bearer description: API key obtained from the dashboard or `GET /user/api-key` ````