Skip to main content

Agent Credentials

Agents sometimes need a secret to do their work — for example, an access token for an external service or a key for a third-party API. Agent credentials are how a worker asks a person for that secret, receives it in encrypted form, uses it for a bounded period, and has it withdrawn afterwards.

This is separate from provider credentials, which are the API keys the platform itself uses to reach AI providers. Agent credentials are secrets an individual worker needs for its own task.

Requesting rather than holding​

An agent starts with no credentials. When it needs a secret it asks a named person, states what it needs and why, and receives it once that person agrees. Each credential it receives carries an expiry.

Requesting on demand keeps the number of live credentials proportionate to the work actually in progress, and ties every secret an agent holds to a person who agreed to provide it and a stated purpose.

The request lifecycle​

StatusMeaning
PENDINGThe agent has asked; the person has not yet responded
SHAREDThe secret has been provided and the agent can retrieve it
DENIEDThe person declined the request
CANCELLEDThe request was withdrawn before being answered
EXPIREDThe request or the shared credential passed its lifetime

What a request states​

FieldPurpose
WorkerWhich worker is asking
NameWhat the credential is called, so the person knows what to provide
TypeAPI key, OAuth token, password, certificate, or a custom type
PurposeWhy the agent needs it — shown to the person being asked
Requested fromThe person being asked
LifetimeHow long the credential remains usable once shared, one hour by default
Work itemThe piece of work the credential is needed for, where applicable

The purpose is what the person reads when deciding. Requiring it up front gives the person the information they need to judge whether the request is reasonable — for example, a request for a production database password should explain why the work requires one.

Sharing and retrieval​

When an agent raises a request, the platform sets up a secure sharing context between the requesting worker and the person being asked, and notifies that person. The secret is provided through Raytio's normal encrypted sharing flow — the same mechanism used for sharing any sensitive data between parties.

The agent therefore retrieves an encrypted payload, which only the worker's own key material can open. The credential stays encrypted everywhere it is held, including in worker configuration, in logs, and in the platform's stored data.

important

An agent can be issued credentials only if it has its own identity in the platform, since that identity is what the credential is encrypted to. Credential requests from a worker without one are refused.

Expiry and revocation​

Every shared credential has a defined end.

  • Expiry is automatic. Each credential carries a lifetime from the moment it is shared, one hour by default. Once that elapses the credential stops working on its own.
  • Revocation is immediate. Revoking a credential marks it withdrawn, closes the sharing context it came through, and cancels any outstanding requests attached to it.

Expiry is the normal path, ending the credential once the work it was needed for is finished. Revocation is for withdrawing a credential ahead of its expiry.

Reviewing outstanding requests​

The WRM toolset covers the whole lifecycle:

  • Request a credential — an agent asks a named person for a secret, stating its purpose
  • Check request status — see where a request has reached
  • List credentials — see what a worker currently holds
  • Retrieve a credential — fetch the encrypted payload for use
  • Revoke a credential — withdraw it immediately
tip

Periodically review the credentials agents currently hold. A credential still active well past the work it was requested for is worth revoking, and worth checking why its lifetime was set as long as it was.