Stop Giving AI Agents the Keys to Everything

The fastest way to connect an AI agent to your tools is often to give it the same credentials you use yourself. The demo works. The agent can read, write, send, and change almost anything. You promise to tighten the permissions later.

But a mistaken tool call now has the authority of your account. So does a request influenced by an untrusted document, a misconfigured workflow, or a leaked credential. A prompt that says “only use this for reporting” does not make a production key read-only.

Least privilege means giving each agent only the access its job needs—and making that limit real outside the model. This guide shows how to separate agent identities, choose exact scopes, check connector permissions, and replace credentials without losing track of who can do what.

We will use a fictional daily-report agent. The workflow and test address are illustrative, not a customer deployment.

Start with the job, not the API key

Our report agent summarizes operational results and prepares an email for a team. That description hides several different permissions: reading source data, recording a trace, checking whether sending is permitted, and actually sending the message.

Do not bundle those permissions merely because one workflow uses them. Write down the operations first:

• Record a run: a telemetry component needs traces:write; it does not automatically need to read stored traces.
• Inspect run history: an investigation client needs traces:read, separately from write access.
• Check a proposed tool action: a preflight client needs gateway:check.
• Request or execute a supported tool action: the relevant gateway route requires gateway:execute, plus the connector's authorization rules.

These are Robots Center API scopes, not credentials for the report's source database or email provider. Those systems need their own access controls. If the agent only needs a small report dataset, do not hand it an unrestricted database login alongside a carefully scoped Robots Center key.

Give different responsibilities different identities

Create a dedicated service-agent identity rather than distributing one shared workspace key to every process. Keep a reporting worker separate from a deployment agent or a credential-provisioning service.

In the console, use Agents → Service agents to create the identity, then Agents → Credentials to issue its credential. Use a descriptive name such as daily-report-preflight-dev and enter the exact scopes it needs. Copy the one-time secret directly into your secret manager.

A separate identity lets you reason about access and revoke one integration without deliberately sharing its key with unrelated workloads. Multiple credentials on the same identity can help with a controlled replacement, but they do not create separate service agents.

Keep development and production credentials separate too. A name ending in -dev, or an environment field in a request, is not an isolation boundary. Use separate workspaces where appropriate, and verify that each credential belongs to the intended workspace.

Understand the two permission checks

An API scope answers “may this caller use this API operation?” A connector grant answers “may this identity perform this action on this connector?” You need both where the gateway requires them.

For example, gateway:check lets an agent ask for an authorization decision. It does not grant permission to send email. Likewise, gateway:execute does not automatically grant every action on every connector. The gateway evaluates matching grants and approval policies; without a matching allow grant, the action is denied.

Scopes are exact. traces:write does not imply traces:read, and gateway:check does not imply gateway:execute. Do not add credentials:write to an ordinary worker just to silence a permissions error: credential provisioning is a separate responsibility.

The gateway reference lists the scopes required by each route. Use it to build an explicit allowlist, not a collection of every scope you might need someday.

Try a check-only credential before enabling execution

For a first test, give the report agent a credential with only gateway:check. Have a workspace administrator configure the email-smtp connector and a narrow grant for the agent's send_email action. Approval policies may still require review.

The following Bash example checks that action without sending an email. It requires curl and an AGENTOPS_API_KEY environment variable injected by your secret manager into a trusted runner. Do not paste the secret into the script, a model prompt, or a support ticket, and keep shell tracing and verbose HTTP logging off.

AGENTOPS_BASE_URL="https://robotscenter.net"
: "${AGENTOPS_API_KEY:?Load the check-only key from your secret manager}"

curl --fail-with-body --silent --show-error \
  --request POST "$AGENTOPS_BASE_URL/api/v1/auth_checks" \
  --header "Authorization: Bearer $AGENTOPS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "connector_slug": "email-smtp",
    "action_name": "send_email",
    "environment": "development",
    "payload": {
      "to": "report-review@example.test",
      "subject": "Daily operations report"
    }
  }'

Inspect the response's decision, not just its HTTP status:

• allowed: the submitted action passed authorization. No email was sent.
• denied: stop and investigate the grant or applicable restriction.
• requires_approval: the action needs review. This check has not created an approval request.

All three decisions can arrive with HTTP 200 from /auth_checks. A successful HTTP request is not the same as permission to proceed. A missing connector returns 404, while a credential missing gateway:check returns 403.

Only after checking the intended boundary should you configure the execution path. /auth_checks never executes a tool; an allowed response from /tool_actions also does not itself execute the connector. Follow the gateway contract for the route your integration actually uses, and the human-approval walkthrough when review is required.

Narrow tokens deliberately—and read the actual expiry

A service-agent API key works directly on protected machine routes. Exchanging it at POST /api/v1/agent_tokens is optional. The exchange accepts the API key in x-agent-api-key or the JSON api_key field, rather than a Bearer credential.

You can request an explicit subset of the key's scopes. Asking for scopes the key does not hold is rejected; omitting scopes or passing an empty list inherits the key's scopes rather than producing a zero-permission token.

The current machine access-token lifetime is 30 days, not a few minutes. Do not describe token exchange as per-task, short-lived access. The underlying credential is checked on subsequent authenticated requests, so its expiry, revocation, or archival can stop access earlier. For a time-bounded API credential, the operator credential API accepts expires_at when creating it.

Socket tokens are different: they have a 600-second lifetime and are for the realtime connection, not a substitute for REST credentials. The authentication guide explains which token belongs on each surface.

Narrowing only helps if the runtime receives only the narrower credential. Giving it both the restricted token and the broader source key leaves the broader access available.

Plan replacement before the old key stops working

Robots Center's Rotate operation issues a replacement credential and immediately revokes the old one. It preserves the existing scopes and expiry; it is not a way to reduce permissions or extend an expiring credential. Do not assume a grace period for the old key or access tokens derived from it.

For a planned migration where a brief overlap is acceptable:

1. Create a separate replacement credential with the desired scopes and, when needed, expiry.
2. Store it securely and update the intended workload.
3. Verify the required operations and the expected denials using the new credential.
4. Revoke the old credential and confirm it no longer authenticates.

Keep that overlap short. If you suspect a leak, revoke the affected credential promptly rather than preserving access for convenience. Investigate what it could reach, and replace any exposed downstream credentials too.

Test the things the agent must not do

An integration that completes its happy path has passed only half the test. In a non-production workspace, verify that:

• A check-only credential cannot call an execution route.
• A telemetry-only credential cannot read stored traces.
• An agent without the connector's allow grant receives a denied decision.
• A token exchange cannot add scopes missing from the source key.
• A revoked credential, and an access token derived from it, no longer authenticate on protected REST routes.

When a request fails, inspect the error before changing permissions. A 401 can indicate an invalid, expired, or revoked credential. A 403 can indicate a missing scope or a workspace restriction. Do not automatically replace either with a more powerful key. Keep request IDs and redacted error details for diagnosis—not authorization headers or full token responses.

Most importantly, test for a bypass. If the agent still possesses the email provider's unrestricted key, a gateway denial cannot prevent it from calling that provider directly. Keep powerful downstream credentials in the trusted execution layer and enforce authorization there. Robots Center does not intercept arbitrary network calls made by your runtime.

Make the smallest useful permission set your default

Before enabling a workflow, identify its owner, service-agent identity, required scopes, connector grants, credential storage, and replacement procedure. Confirm at least one operation it is allowed to perform and one it must be refused.

Start with one agent and one supported action. Expand access when a specific job requires it, not because a demo becomes easier with an administrator's key.

The goal is not to make the agent promise to behave. It is to make sure a mistaken request cannot borrow more authority than the job requires.

Use the authentication guide to set up the credential, then the policy simulator guide to inspect connector decisions before connecting a live execution path.