An agent that reads a user's Gmail should not know the user's password. An agent that manages a user's calendar should not share credentials with every other agent in the fleet. These statements sound obvious. Most agent frameworks violate them anyway, usually through a long-lived service account that stands in for every user the agent acts on behalf of.
The OAuth adapter is how a venue (the running instance of the Covia coordination layer the agent executes within) attaches a user's scoped, time-bounded credentials to an agent at runtime. The user consents once, in a browser flow they already know. The venue stores the refresh token. The agent asks for an access token at the moment of action. Each token is short-lived and scoped to the single resource the agent is about to touch. Credential brokering lives in the coordination layer rather than in the agent for a reason: the layer already sits in the request path, checking authority before every action. Consent is one more authority decision, so it belongs where authority is already checked.
This piece walks through why password sharing and shared service accounts both fail, how the OAuth adapter brokers consent, how an action pulls an access token at runtime, what the venue writes to its signed record, and three failure modes the adapter closes.
Why password sharing and service accounts both fail
Two patterns developers reach for first both fail audits, both fail security reviews, and both fail at scale.
Password sharing is the first instinct and the worst option. The agent prompts the user for a password, stores it somewhere, and reuses it. The failure modes are too familiar to list: credentials in logs, credentials in prompts, no way to revoke access short of the user changing their password everywhere, no way to scope what the agent can do with the credentials. Any serious enterprise rejects this pattern before the first review.
Service accounts are the second instinct. The platform creates one long-lived identity, grants it broad access to Gmail, Slack, GitHub, and the rest, and every agent in the fleet acts under that identity. The audit trail attributes every action to "ai-ops-service-account." It cannot say which user the action was done on behalf of. It cannot say which agent inside the fleet made the request. It cannot say whether the specific user who asked for the action had the right to that resource today. The platform's blast radius is one credential compromise away from the entire organisation.
Neither pattern survives the question an auditor will ask: on whose behalf did the agent act, and what proof do you have that the user consented?
How the OAuth adapter brokers consent
OAuth 2.0 is the standard web authorisation protocol. Google, Microsoft, GitHub, Slack, and most SaaS providers implement it. The adapter is the Covia component that wraps the standard flow and makes its output usable by an agent at runtime.
The user starts the flow from the venue. The venue redirects the browser to the provider's consent screen. The user sees exactly what the agent is asking for, usually in the form of OAuth scopes (gmail.readonly, calendar.events, and so on). The user approves. The provider redirects back to the venue with a short-lived authorisation code. The venue exchanges the code for a refresh token and stores the refresh token in the venue secret store.
Three properties of this flow matter.
The password never leaves the user's browser. The venue never sees the password. The agent never sees the password.
The user approves specific scopes. The user grants only the specific permissions the agent asked for, which the provider shows them explicitly before they approve.
The user can revoke. The user can log into the provider's account settings and revoke the venue's grant without changing their password or touching any other integration.
The venue secret store is the one place in the venue that holds the refresh token. Access to the secret store is subject to the same authority checks as any other venue operation. See the OAuth adapter documentation for the exact operation names and the secret-store contract.
How an action pulls an access token at runtime
The refresh token in the secret store is not usable directly. OAuth refresh tokens exchange for short-lived access tokens at the point of action.
A credit-review agent that needs to read a user's Gmail issues a request like this to the venue:
{
"operation": "v/ops/oauth/token",
"input": {
"user": "did:key:z6Mk...",
"provider": "google",
"scope": "gmail.readonly",
"resource": "mail.google.com/user/me/messages"
}
}The venue checks the agent's authority to request a token on behalf of this user, for this scope, against this resource. If the check passes, the venue exchanges the refresh token with the provider and returns a short-lived access token to the agent. The access token is valid for one hour at most on most providers. The scope is narrower than the user's full grant.
The agent uses the access token to call the provider's API. When the token expires, the agent asks the venue for another one. The venue repeats the check each time.
Four details are worth naming.
The access token is scoped per request. The agent asked for gmail.readonly, so the provider only accepts actions within that scope.
The access token is short-lived. A one-hour validity window means the blast radius of a leak is one hour, not forever.
The agent never sees the refresh token. The agent sees only the access token. Even if the agent is compromised, the attacker gets at most one access token's worth of access.
The venue checks authority on every exchange. Authority can change between requests. If the user has revoked the grant, or if an administrator has revoked the agent's permissions, the next exchange fails. No cached tokens, no stale authority.
What the venue writes to the record
For every OAuth exchange, the venue writes an entry to its signed record. The entry contains the agent's identifier, the user's DID (their unique digital identifier), the provider, the scope requested, the resource requested, the authority check result, and a hash of the access token. The access token itself stays out of the record. The refresh token is never written outside the secret store.
The record stores the hash in place of the token. This keeps the record useful (an auditor can verify which exact token was issued) and prevents the record from becoming a bearer-credential store. If an attacker compromises the record, they get hashes.
The entry is signed by the venue at the moment of action. See the UCAN model for how the authority check that gates each exchange is expressed in Covia's capability system.
Three failure modes the adapter closes
The adapter closes three failure modes that any serious enterprise integration review will raise.
Credential leakage into model context. Many agent frameworks pass credentials to the model as part of the prompt or the tool-call payload. Once credentials are in the prompt, they are in the inference provider's logs, the LLM's rolling context, the trace captures of any observability tool watching the stack, and, often, the training feedback loops of the model provider. The OAuth adapter resolves credentials inside the venue. The access token is handed to the agent at the moment of action and used in a single provider call. It never enters the model's prompt.
Blast radius on compromise. A compromised agent process with a shared service-account credential grants the attacker everything that service account can touch, until a human notices. A compromised agent process using the OAuth adapter has access to one user's scope for one hour. The attacker has to compromise the venue to escalate further. The venue is a smaller, better-defended surface than the agent fleet.
Attribution to the wrong principal. A service account cannot say which user the action was performed on behalf of. The OAuth adapter writes the user's DID into every record. The audit question "did Priya approve this agent reading her email on Tuesday?" has an answer in the record and the answer carries the venue's signature.
How this runs in Covia
Covia implements the OAuth adapter as a first-class venue operation, and the full agent surface is built around it. The refresh token lives in the venue's secret store, which the agent cannot read. Every token exchange is gated by the same capability check that gates every other action the venue serves, so a revoked grant or a revoked agent fails on the next request. Every exchange is receipted into the venue's lattice, its content-addressed, append-only record, and signed by the venue at the moment of the exchange.
The pattern is the venue's governance model applied to credentials: authority checked at the moment of action, a signed receipt per exchange, and a durable record an auditor can query years later. The governed coordination layer piece defines those properties in full.
For the engineer
If you are building agents that act on third-party services, the adapter model has a specific shape. The venue holds refresh tokens. The agent asks for access tokens at the moment of action. The venue checks authority, exchanges with the provider, and returns the short-lived token. The record names the user, the scope, and the authority used, signed by the venue.
Password sharing fails every serious security review. Shared service accounts fail every serious audit. The OAuth adapter is the pattern production agents use when the people reviewing the system can read.
The audit question is the one that decides whether an agent fleet survives review: did Priya consent to this agent reading her email on Tuesday, and can you prove it? Password sharing cannot answer it. Shared service accounts cannot answer it. A venue that brokers consent, checks authority on every exchange, and signs each answer into a durable record can. That is the enterprise case for running credential delegation inside the coordination layer. The adapter documentation has the specific operations and the configuration contract.