# Give an agent access

Grant an agent short-lived access profiles or static secrets, approve on-demand access requests, and revoke access immediately.

Let an agent authenticate to GitHub, Google Cloud or AWS through a project **access profile**, or pass a stored **secret** (such as an API key) to specific shell commands.

To grant an access profile, you need `connections.accessProfiles.issue` on the profile (Owner, Connection Admin or Access Profile Accessor). To grant a stored secret, you need `secrets.versions.access` on the secret (Owner, Secret Manager Admin or Secret Accessor). In both cases you also need write access to the agent (`agents.secretGrants.create`).

:::warning
Anyone who can write to an agent can direct it to use what it has been granted. Grant agents only the access their task needs, prefer read-only access profiles with a time limit (TTL), and revoke grants once work finishes.
:::

## When you start an agent [#when-you-start-an-agent]

1. In your project, click **New agent**.
2. Click the **Access** picker in the composer strip.
3. Select one or more **Access profiles** (with optional scope narrowing and duration) or **Secrets**.
4. Selected grants appear as removable chips in the composer strip. Notice that only read-only access profiles carry over automatically onto new project-visible agents; write access profiles and static secrets are never carried over automatically.
5. Describe the task and start the agent.

## On a running agent [#on-a-running-agent]

1. Open the agent and click the **Access** picker in the composer strip.
2. Add an access profile (optionally narrowed and time-limited) or a stored secret, review who can use it on this agent, and confirm.
3. To revoke a grant immediately, click the remove button on its chip or open the picker.

## On-demand access requests [#on-demand-access-requests]

When an agent hits a task that needs access it doesn't have yet (such as pushing a branch or reading an API key), it can call `request_access` to pause and ask you in the transcript. An inline **Access request** card lets you approve (optionally narrowing scope or setting a shorter duration) or deny the request, and the agent continues automatically with the decision.

## How the agent uses granted access [#how-the-agent-uses-granted-access]

- **Access profiles work automatically:** kosem configures `git`, `gh`, `aws`, `gcloud` and standard cloud SDK metadata inside the agent's environment. Credentials are minted on demand through `/run/kosem/creds.sock`, narrowed to the grant's scope, and redacted automatically from live command output.
- **Static secrets are passed per command:** the agent passes a granted secret to a single command via `exec`'s `secrets` argument (`VAR=alias` or `file:name=alias` under `/run/kosem/secrets`). Values are never persisted in shell state and are redacted from live output.

Each credential issue (`connections.IssueCredentialForEnvironment`) and secret use (`secrets.UseSecretVersion`) is recorded in the System Events audit log with the agent, environment and grantor.

## Revoke access from an agent [#revoke-access-from-an-agent]

You can revoke a grant in two ways:

- **From the agent:** anyone with Owner on the agent, or Owner or Agents Admin on its project, can remove any grant from the composer strip or agent settings.
- **From the resource:** an IAM admin of the access profile (`connections.accessProfiles.setIamPolicy`) or secret (`secrets.secrets.setIamPolicy`) can open the resource's **Agents** tab and click **Revoke** on any agent row, including private agents.

Revoking a grant immediately invalidates cached credentials in the agent's running environment over its tunnel so subsequent commands stop receiving them right away. Already-minted provider tokens remain valid upstream until their short expiry (such as GitHub's 1-hour token), and values already read by a command can't be unread — rotate static secrets if exposed.

## Related [#related]

- [Connections and access profiles](/concepts/connections)
- [Create an access profile](/guides/secrets/create-an-access-profile)
- [Secrets](/concepts/secrets#secrets-for-agents)
