Credential aliases for AI agents: safer local actions

Agents should ask for a connection by name, not receive the credential that makes the connection work. That sounds like a small API design choice. It is actually the line between an agent that can act within a boundary and an agent process that holds a pocketful of reusable secrets.

I have seen teams call a secret GITHUB_TOKEN, place it in an agent's environment, and congratulate themselves because the tool interface looked tidy. The token still lands in process memory, shell history, debug output, child processes, and sometimes the agent's own working notes. Renaming exposure does not reduce exposure.

Credential aliases for AI agents work when a trusted local executor resolves a short, human-readable connection name and performs the authenticated request itself. The agent asks for repo-release-prod; the executor injects the credential at the point of use; the agent gets a status code, a response body that has been filtered for secrets, or command output. The secret never becomes input or output of the agent loop.

That boundary has to be designed with more care than most first versions get. An alias can provide a clean operational handle, easy rotation, and useful audit records. It can also become a decorative label over broad, permanent authority if you do not define what the name permits, who can invoke it, and how you can stop it.

An alias names authority, not a hidden string

A useful credential alias names a service connection with a specific purpose. It does not name a database of secrets that the agent can browse, and it does not promise that every request carrying the alias is acceptable.

Take payments-prod. That name is too vague for an autonomous agent. Does it permit reading invoices, issuing refunds, editing account data, or downloading reports? A single bearer token may technically do all of those, but the alias should not erase the distinction. Better names expose the operational intent: payments-invoice-read-prod and payments-refund-review-prod tell an operator what they are about to authorize and make an audit record readable six months later.

People routinely blur three different things:

• A secret reference identifies stored material, such as a vault path or secret ID.
• A credential alias identifies a usable authenticated connection.
• A capability name identifies an allowed operation, such as publishing a release or reading a build log.

These can map one to one in a small setup, but they should not become the same concept by accident. A secret reference might point to a token that can call many endpoints. A connection may require a token plus a client certificate. A capability may need different connections in different environments. If you collapse them, rotation, review, and incident response become harder because nobody can tell which part changed.

I prefer aliases that include the target service, environment, and job, while omitting the credential type. artifact-publish-prod is better than artifact-api-token-2. The first name survives a migration from a static token to a short-lived exchange. The second bakes an implementation detail into every agent prompt, tool call, test, and runbook.

Do not let agents enumerate all aliases by default. A list of connection names often gives away internal service names, environments, and privileged workflows. More importantly, enumeration turns a constrained agent into a curious one. Give a task the small set of names it needs, or expose an operation-oriented tool that selects the connection internally.

A secret outside context must stay outside every path

Keeping the token out of the main model prompt is necessary, but it is nowhere near sufficient. A credential escapes when any component in the agent's reachable process tree can read it or persuade another component to print it.

Consider a familiar failed design. A coding agent calls a local helper with connection=deploy-prod. The helper looks up an API token, then starts a command-line client with that token in an environment variable. The command fails. A diagnostic wrapper prints its environment to a log file. The agent has filesystem access to the workspace log directory and reads the token in order to explain the failure.

No one intended to reveal the secret. The architecture did it because the helper treated an environment variable as a private channel. It is not private from child processes, crash reports, diagnostics, or any command that can inspect its own environment. Putting credentials in command arguments is worse because process inspection and shell history can expose them.

The local executor should hold the credential in its own protected storage, construct the authenticated request in memory, and return a deliberately limited result. For HTTP, that usually means it adds the authorization header itself. For SSH, it means it selects the private key or invokes a helper that can use the key without handing the key file path and contents to the agent.

The response path deserves equal attention. Some APIs return credentials during token creation, webhooks may echo authorization data, and error reports can include request headers. The executor needs a response policy that removes known secret-bearing headers and avoids reflecting its own request construction. This is not a reason to silently rewrite business data. It is a reason to decide which parts of a request and response the agent is entitled to see.

A clean test is more useful than a design diagram. Ask the agent to retrieve the alias value, dump tool settings, provoke an authentication error, inspect running child processes if it can, and read every log location it can access. The expected result is boring: it finds a name and action outcomes, but no token, password, private key, or reusable signed request.

Connection scope must fit the action surface

An alias is only as narrow as the authority behind it. A perfectly concealed administrator token remains an administrator token.

For HTTP services, scope starts with the service account or token permissions. Give a release agent permission to create a release and upload the required artifact. Do not attach repository administration, organization membership, billing access, or user impersonation because they might be useful later. That later need should produce a separate review and usually a different connection.

Endpoint restrictions belong in the executor when the service's own authorization model cannot express them. This is where teams often reach for a large policy language. It looks flexible during a demo and becomes a maintenance problem when an operator has to predict whether an unfamiliar request will pass. If you need endpoint restrictions, make them visible and small: allowed method, host, path family, and expected credential. Treat unusual request bodies and redirects as cases that need a conscious design, not incidental exceptions.

SSH needs the same discipline, even though its controls look different. A key that opens an interactive shell gives an agent a very large action surface. Prefer an account that can perform the required task in a limited directory, or a forced command that accepts the precise operation you intend. Do not assume a host alias in ~/.ssh/config solves this. That alias picks a destination for a client; it does not constrain what happens after authentication.

The OpenSSH authorized_keys manual documents options such as command=, no-pty, no-port-forwarding, and restrict. Those are practical tools for machine connections. They also have sharp edges: a forced command must validate its arguments, and a restriction that blocks port forwarding does not make a broad shell account safe. Read the effective account permissions first. Then use SSH options to reduce paths you do not need.

Do not use one alias for both staging and production because the endpoint happens to differ in a URL parameter. An agent makes mistakes under pressure just like a person does. Separate names let you set separate credentials, approval treatment, and audit expectations. They also prevent a staging task from acquiring production authority through a string substitution bug.

The executor must authenticate the caller before honoring the alias

A credential alias protects nothing if any local process can invoke it. The executor needs a clear answer to a plain question: which process asked for this action?

Process IDs alone are not an identity. They are short-lived and can be reused. A process name is worse because another program can use the same name. On macOS, code-signing authority gives an approver better information about the executable behind a request, although it does not make the requested action safe by itself. The operator still needs to judge whether that signed process should receive this connection for this session.

Per-session authorization works well for agents that issue many related calls. The first request from a new agent process presents the calling identity and the requested run. Approval covers that process until it exits. This avoids asking a human to approve a routine sequence of small calls while preserving a boundary between separate runs.

Some aliases deserve a decision on each use. Production deployment, destructive API operations, and access to customer data are reasonable candidates. The approval screen should show the alias, destination, operation, and caller identity in plain language. Asking people to approve an opaque event is how you train them to click through it.

RFC 6749 makes a useful separation that agent tool builders should keep: the authorization server issues access tokens, and the resource server accepts them. The agent is neither of those by necessity. In a local executor design, the executor can act as the component that holds or obtains the credential and sends the authenticated request. The agent can remain a requester of a narrowly described action. That is a cleaner separation than treating the agent as a general OAuth client just because it can make HTTP calls.

This does not mean every agent needs interactive approval. A controlled build worker may have a narrow, preapproved connection. The question is whether you can identify the caller and whether the authority matches its assigned job. If neither answer is solid, an alias has only hidden a local privilege escalation behind a friendlier interface.

Rotation should change material without breaking the name

The operational payoff of aliases appears during rotation. You replace the token or SSH key behind artifact-publish-prod; the agent keeps requesting the same connection name; no prompt, source file, or agent configuration needs the new secret.

That does not mean an alias should live forever. Keep the name stable only while its meaning stays stable. If a token changes from read-only access to write access, the old name now lies. If ownership moves from one team to another, the old approval expectation may no longer fit. If a credential moves from a test tenant to a production tenant, create a new alias even if the API is identical.

The rotation sequence should prove both sides of the change:

1. Add the replacement credential behind the existing alias and make one narrowly scoped health call through the executor.
2. Revoke or disable the old material at the service provider, then repeat the expected agent action.
3. Inspect the audit record for failed retries or unexpected callers, because stale processes often reveal themselves after a rotation.
4. Remove copied credential files, old environment settings, and emergency scripts that bypassed the executor.

The last item is where rotations fail in practice. Someone creates a temporary token to keep a release moving, leaves it in a CI variable or local script, then forgets it. The polished alias path rotates cleanly while the abandoned bypass keeps working. You have not completed rotation until you have found and closed the alternate path.

The OWASP Secrets Management Cheat Sheet advises teams to rotate secrets and apply least privilege. Both recommendations are right, but they are usually presented as storage hygiene. For agents, rotation also protects the instruction layer. A stable alias means model context does not contain a changing secret and does not need a secret update task that might appear in transcripts, commit messages, or tool output.

Audit records need to describe decisions without recording secrets

Logs should let you answer who requested an action, what connection they requested, what the executor did, and whether it was approved. They should never become a convenient copy of the credential vault.

A practical event record includes a timestamp, session identifier, caller identity, alias, channel, destination, method or command class, authorization decision, and result class. For an HTTP call, recording POST /releases is usually enough to explain the action. Recording the full Authorization header is never useful and creates a severe cleanup problem. For SSH, record the host alias, remote account or command class, and exit status, not a private key fingerprint if that fingerprint reveals a sensitive inventory detail.

Keep the session record and individual action record distinct. A session tells you when an agent run began, which local process owned it, and whether you revoked it. Individual records tell you what happened inside that run. If you merge them into one vague activity feed, revoking a suspicious run and finding its actions take longer than they should.

Tamper evidence changes the quality of an audit trail. An append-only file is easy to edit for anyone who can alter the file. A hash chain makes later modification detectable because each entry incorporates the previous entry's digest. It does not prevent deletion, and it does not prove a malicious executor recorded truthful content. It does make quiet rewriting much harder to pass off as history.

A useful verification command has an intentionally simple contract:

$ sp audit verify
verified 184 records
chain: valid
first record: 2025-04-03T09:14:22Z
last record:  2025-04-03T16:48:01Z

The exact count and timestamps will differ. What matters is that verification reads the stored encrypted record stream, checks the chain, and reports an invalid position when someone changes a record. Offline verification over ciphertext is especially useful because an investigator can check continuity without opening the vault or exposing the stored action details.

Do not confuse tamper evidence with monitoring. You still need to look at suspicious activity, preserve copies when an incident starts, and decide who has authority to revoke sessions. Cryptography can tell you that a record sequence changed. It cannot tell you that delete-production-data was a sensible request.

Approval fatigue is a sign of bad alias design

If a person must approve every harmless action, they will approve without reading. That is not a people problem. It is a system that refuses to distinguish routine authority from consequential authority.

Use session approval for a bounded agent run whose allowed connections have ordinary operational risk. The approval should identify the code-signing authority of the process, because a label such as agent says very little. If that process exits, require another approval for the next process. This contains a copied tool invocation better than a one-time approval that stays valid indefinitely.

Use per-call approval for aliases where every invocation deserves scrutiny. The executor should make the decision event legible enough for a human to reject it quickly. Use payments-refund-review-prod to submit refund request for order 4821 is actionable. Tool call requires approval is lazy design.

Sallyport uses a fixed decision ladder for this reason: a locked vault denies every action, a new agent process requires session authorization by default, and individual credentials can require approval on each use. It avoids a policy language because local operators should not have to debug an authorization interpreter before they can stop an agent.

Do not turn each confirmation into a debate with the agent. An approval is a control point, not a conversational prompt. Reject the action, revoke the session if the run has gone off course, and inspect the preceding records. If a task needs frequent exceptional approvals, revise the task boundary or create a narrower connection with authority that matches the recurring work.

Aliases do not cure prompt injection or bad task design

Credential isolation limits the damage from secret theft. It does not decide whether an agent should call an API, upload a file, or run a remote command.

A prompt injection hidden in a repository issue can tell an agent to publish a release, exfiltrate a report through an allowed endpoint, or use an SSH connection for a command that falls within a broad account's authority. The alias did its job if the attacker never acquired the token. The agent may still perform a harmful allowed action.

This is why a wide alias is dangerous even when the secret never leaks. cloud-admin-prod gives an injected instruction too much room. artifact-publish-prod, paired with a restricted service account and an expected destination, gives it less. You still need to limit what files the agent can read, separate untrusted content from action instructions, and ask for approval around actions whose consequences exceed the task.

Another weak design exposes a generic http_request tool plus an alias parameter. The agent can then point a powerful credential at arbitrary paths, hosts after redirects, or endpoints the operator never considered. A purpose-built tool such as create_release has less flexibility, but that is often a security benefit. Generality is not neutral when an agent follows untrusted text.

Treat every alias as an answer to a sentence you can write down: “This identified process may perform this class of action against this destination with this approval treatment.” If you cannot write the sentence without words like “anything” or “as needed,” the connection needs more design before an agent receives it.

A local executor should stay boring and inspectable

The executor has more privilege than the agent, so it should do less than the agent. It needs encrypted credential storage, a small set of action channels, caller identification, decision handling, and audit recording. It does not need to become a remote access gateway, an all-purpose proxy, or a custom rules language with hundreds of exceptions.

For a local development setup, a menu-bar application can make the vault state and pending approvals visible without adding a separate background service that operators forget exists. That does not remove the need for careful engineering. It does put the sensitive operation in one place that can lock, deny requests, and maintain its own records.

Sallyport keeps API keys and SSH keys in an encrypted local vault and executes HTTP and SSH actions on behalf of MCP-capable agents, rather than passing credentials into the agent context. Its sp mcp shim gives an agent a normal stdio connection while the app remains the executor.

Inspectability means an operator can answer basic questions without reading source code during an incident: Is the vault locked? Which run is active? Which connection did it request? Can I revoke that run? Did the recorded sequence change? If the answer requires joining logs from five different components, the system may be clever but it is not manageable at 2 a.m.

Keep the tool protocol narrow. Return structured success and error results. Avoid error messages that include internal request objects or secret storage paths. Make cancellation explicit so a user can stop a long-running action without killing unrelated work. Those choices look ordinary. They are the difference between a boundary you can operate and a boundary you merely hope is present.

Test the boundary like an attacker who can write prompts

A happy-path demo proves only that the alias resolves. Before you trust the design, test the ways an agent or a compromised plugin would try to turn a connection name into broader access.

Start with an alias that points to a nonproduction service account. Run an agent task that makes the intended call, then give it adversarial instructions to inspect tool schemas, request configuration dumps, trigger malformed requests, follow redirects, start child commands, and read accessible logs. Review both its visible transcript and the executor's records. You are looking for secret material, unexpected destinations, and calls that bypass the intended action boundary.

Then test failures deliberately. Lock the vault during a request. Revoke the session before the second call. Rotate the underlying credential. Change one stored audit record in a copy and run verification. Each expected failure should be clear to the operator and unhelpful to an attacker. “Access denied because the vault is locked” is fine. A stack trace containing a vault record or header value is not.

Finally, test the awkward operational case: an agent run is doing legitimate work when its behavior becomes suspicious. Can the operator identify the run, revoke it immediately, determine what calls already succeeded, and verify that the record sequence has not been edited? If those actions take a scavenger hunt through terminals and cloud dashboards, fix that before adding more aliases.

A named connection is a small interface with large consequences. Make its name honest, its authority narrow, its caller identifiable, and its records useful. Then let the agent request actions without ever giving it a secret worth stealing.