AIP-69: AUTH-PROFILE (auth-profile/v1): a named reference to the credential that pays for a session
A runtime primitive for the account a session bills or authenticates through: a named, harness-independent reference to a credential on one billing endpoint, never the secret. Fixes the AuthProfile document (endpoint, method, credential reference, sub-account, subscription), the eligibility predicate that decides which profiles can serve a given harness and route, the profile as an AIP-38 resource (which models it may serve, who may use it, how much it may spend), the read surface, and the contract for re-authenticating the account behind a profile (parent and sub-account modeling, expiry, a typed "log in again" error). Referenced by AIP-46 sessions, AIP-67 quota and AIP-38 policy.
| Field | Value |
|---|---|
| AIP | 69 (provisional, editors assign the final number) |
| Title | AUTH-PROFILE (auth-profile/v1): a named reference to the credential that pays for a session |
| Author | Jeremy André <[email protected]> |
| Status | Draft |
| Type | Standards Track |
| Requires | AIP-19, AIP-29, AIP-37, AIP-38, AIP-39, AIP-43, AIP-45, AIP-67 |
| Created | 2026-10-23 |
| Reference implementation | @agentproto/auth (profile-types.ts), shared with AIP-50 |
| Resources | ./resources/aip-69: AuthProfile.schema.json |
Abstract
An auth profile is the account a session runs on: a named reference to a credential that authenticates against one billing endpoint (a provider API, a gateway, a subscription), plus what the user declares about it. It is never the secret.
This AIP defines:
- the AuthProfile document;
- eligibility: which profiles can serve a given harness, route and model;
- the profile as an AIP-38 resource: which models it may serve, who may use it, how much it may spend;
- the read and write surface, which never returns credential material;
- the parent account behind a profile and the sub-accounts it owns, the expiry a read reports for it, and re-authentication: the verb that logs the parent in again, how it is verified, and the typed error a spawn returns when it is needed.
Three AIPs already depend on this concept without owning it:
AIP-46 binds a session to a profile (access.profileRef) and
amortises a subscription over it, AIP-67 reads quota keyed by
profileRef, and AIP-29 / AIP-19 describe how
a credential is obtained and stored. This AIP is the document they point to.
Motivation
A host that runs harnesses juggles several accounts per vendor: a Claude subscription and a Claude API key, three sub-organizations of one gateway, a free tier and a paid tier of the same key. The questions a host must answer on every spawn are about the account, not about the model:
- which accounts can pay for this harness on this route?
- may this session use that account at all?
- which models is that account allowed to serve?
- how much has it spent in the window, and how much is left?
Today the answers are spread over four documents (AIP-46 §Access profile for amortisation, AIP-67 for quota, AIP-29 for login, AIP-19 for secret storage) and the reference implementation grew a richer shape than any of them (sub-accounts, extra routes, per-profile model allow-lists, per-profile spend caps, enable/disable). Each of those additions invented its own rule (an allow-list field, a budget field) next to AIP-38, which is the access primitive. This AIP gives the account one owner and routes its rules through AIP-38.
Specification
The key words MUST, MUST NOT, SHOULD, and MAY are to be interpreted as described in AIP-1.
1. AuthProfile
interface AuthProfile {
id: string // stable, unique on the host; the `profileRef` others use
label?: string // human name ("work OpenRouter")
endpoint: string // the billing endpoint the credential authenticates against
routes?: string[] // other billing endpoints the SAME credential is enrolled on
method: "api-key" | "oauth-bearer" | (string & {})
credentialRef?: string // opaque handle into the host's credential store
source?: string // a self-refreshing credential source; exclusive with credentialRef
subaccount?: { kind: string; id: string; name?: string } // org / workspace / project pin
subscription?: Subscription // a flat-rate plan behind the credential (section 4)
policy?: PolicyRef // AIP-38 resource policy (section 3)
disabled?: boolean // skipped by eligibility when true
origin?: string // provenance when imported from a harness or env; informational
}endpointnames who bills, not who built the model: an OpenRouter key serving a z-ai model hasendpoint: "openrouter".routesexists because one credential can be enrolled on more than one endpoint (a key valid on both a subscription route and a pay-as-you-go route of the same vendor). Absent means[endpoint].- At most one of
credentialRefandsourceis present:credentialRef: a credential the host stores. It SHOULD be an AIP-19 secret slug when the host keeps an AIP-19 inventory; how it was first obtained is the harness's AIP-29auth.loginflow.source: a credential the host resolves fresh at spawn from a named source it does not store (a harness's own OAuth login such asclaude-code-oauth, an environment variable such asenv:OPENAI_API_KEY).- neither: an ambient credential, read by the harness itself from its own login state. The host cannot fingerprint it; it MUST show the profile as ambient and MUST NOT claim a fingerprint for it.
subaccountpins one wallet of a multi-wallet account. Each pinned sub-account is its own profile, so quota (AIP-67), spend and policy are per sub-account.methodis how the credential is presented. It is a facet of the profile, not of the session: "subscription" versus "API key" is not a session property.
A profile document MUST NOT contain credential material. Profiles live in host configuration, never in a workspace or a repository.
2. Eligibility
A host resolves a session's (harness, route, model) to a billing endpoint
E and the set M of methods the harness can present on that route. A
profile p is eligible when all hold:
p.disabledis nottrue;p.endpoint == EorE ∈ p.routes;p.method ∈ M;- the AIP-38 evaluation of
model:invokeon that model, againstp's resource policy, allows (section 3).
Rules 1 to 3 MUST be evaluated without I/O. M comes from the harness's
AIP-45 manifest when it declares presentable methods per
route (see Open Questions); until AIP-45 has that field, from a
host-maintained table per harness, which the host MUST expose read-only so
a refusal can be explained. A spawn that names a
profile which is not eligible MUST be refused before the harness starts,
with a refusal code (auth_profile_ineligible) and the failed rule; a host
MUST NOT silently substitute another profile.
When a spawn names no profile, the host MAY pick one: it MUST pick only among
eligible profiles the subject may use (auth-profile:use, section 3), in an
order the user can see and configure, and MUST record the chosen
profileRef on the session.
3. The profile as a policy resource
An auth profile is an AIP-38 resource. Its policy is a
resource policy, evaluated together with the subject's policy (the AIP-42
agent's policy, the user's) under AIP-38's resource and subject rule:
both must allow when both exist; a profile without policy defers to the
subject policy alone.
The actions involved are the AIP-39 standard runtime actions:
| action | scope | asked when |
|---|---|---|
auth-profile:use | the profile id | a session is bound to the profile (spawn, restart, fallback) |
model:invoke | the model id, glob, or selector:<id> | the session's model is set or changes while bound to the profile |
What an implementation used to express with ad hoc fields maps as follows:
| ad hoc field | AIP-38 form |
|---|---|
per-profile model allow-list (models: { mode: "allow", ids }) | a resource policy with default: deny, one grant { principal: "*", actions: [auth-profile:use] }, and one grant { principal: "*", actions: [{ action: model:invoke, scope: <id> }] } per id |
models: { mode: "all" } or no models | no resource policy for model:invoke (the subject policy alone decides) |
per-profile spend cap (costBudget, scope: "profile") | a spend-usd limit with scope: "auth-profile" and a rolling ISO-8601 window ("5h" becomes "PT5H") |
| "only this team may use the company key" | a grant of auth-profile:use to that principal |
| "never this model on this key" | { effect: deny, actions: [model:invoke], scope: <id> } |
A host MAY keep these short forms (models, costBudget) in its
configuration surface. It MUST evaluate them exactly as the AIP-38 forms
above, and it MUST report decisions in the AIP-38 decision record, so an
audit consumer sees one vocabulary. Note one behaviour change for spend
caps: an AIP-38 spend-usd limit refuses the next model:invoke once the
window is exceeded, where the reference implementation's costBudget only
reported an overage at turn end.
A nested session (AIP-46 delegation) inherits no right to its parent's
profiles: auth-profile:use is evaluated for the child's own subject policy,
bounded by the parent's (AIP-38 delegation ceiling). A child MUST NOT be able
to bind a profile its parent could not.
4. Subscription
interface Subscription {
monthlyUsd: number // declared plan price, major units
windows?: Array<{ kind: "5h" | "weekly" | (string & {}); limit?: number }>
}This is the block AIP-46 §Access profile introduced for cost amortisation;
this AIP becomes its owner. Its meaning is unchanged: AIP-46 amortises
monthlyUsd over the profile's usage, and the windows feed that formula.
Headroom (how much of a window is left) is AIP-67, keyed by
the same profileRef.
The session's billingMode (AIP-46) is derived, never declared on the
profile:
"subscription"when the profile has asubscription;- otherwise
"free"when the catalog (AIP-43) prices the session's model at zero on the profile's endpoint; - otherwise
"api".
windows[].kind names a provider-defined window (5h, weekly), not a
duration: its length and reset are the provider's. Durations elsewhere
(AIP-38 limit windows) are ISO-8601.
5. Surface
A conforming host exposes, through its usual projections (MCP tool, HTTP, CLI):
| verb | input | output |
|---|---|---|
auth_profile_list | optional endpoint filter | profiles, each with a fingerprint of the credential, never the value |
auth_profile_create / auth_profile_update | a profile, plus the credential when creating | the stored profile (no secret) |
auth_profile_delete | id, force? | refused while a live session is bound to it, or while a session preset, a fallback overlay or a policy names it (unless force) |
auth_profile_set_enabled | id, enabled | the stored profile |
- A read MUST NOT reveal credential material, in any field, log line or error message. A fingerprint is a short, non-reversible digest.
- A write that stores a credential MUST write it to the credential store
(AIP-19 vault, OS keychain) and keep only
credentialRefin the profile. - Changes MUST be applied to new bindings only. A live session keeps the profile it was bound with until it is restarted (AIP-46).
- A reference to a profile that no longer exists (a forced delete) makes the referring config ineligible. A host MUST NOT substitute another profile for it.
6. Events
Binding, refusing and unbinding a profile are host lifecycle events
(AIP-37, host-namespaced), carrying profileRef, the
session id and, on refusal, the eligibility rule or the AIP-38 decision
record. They never carry credential material.
7. Parent account and sub-account
A parent account is the login a credential source is bound to (a console
login, a harness's own OAuth login). It may own zero or more
sub-accounts: organizations, workspaces, projects. A profile's
subaccount pin (section 1) names one of them.
- The login belongs to the parent, never to a sub-account. A host MUST resolve a sub-account profile's credential from the parent account that owns the pinned sub-account, and MUST NOT resolve it from whichever account the provider's own client currently has active. When no stored login owns the pin, or the owning login is expired or rejected, the host MUST refuse (section 10) and MUST NOT fall back to another login.
- Re-login is per parent. One re-authentication (section 9) of the parent makes every sub-account profile under it usable again. Switching from one sub-account to another is a change of profile, and MUST NOT require a re-login while the parent's session is valid.
- A source with no sub-account concept has a parent and no sub-accounts; its profiles are the degenerate case.
- Which account a provider's client considers active is provider state, not part of this document. A host MUST NOT depend on it for resolution.
8. Expiry on reads
auth_profile_list (section 5), and any other read that lists a profile
whose credential comes from a source, SHOULD add, read from the parent
account's session (or the OAuth credential of a harness login):
interface AuthStatusFields {
expiresAt: string | null // ISO-8601, the parent session's expiry; null when none is known
state: "ok" | "expiring" | "expired" | "unknown"
parent?: { source: string; id?: string; label?: string; loggedIn: boolean }
note?: string // a caveat worth showing (why no expiry, ...)
}stateis derived fromexpiresAtand the clock:expiredwhen less than 60 seconds remain (a session that close to its end is already unusable at spawn),expiringwithin 24 hours,okbeyond that,unknownwhen no expiry is recorded or readable (an API key, a source that does not expose one).- No stored login for the parent is
expiredwithparent.loggedIn: false: there is nothing to spawn with. - A source whose own client renews the access token itself (and holds a
refresh token) SHOULD report
unknown, keepexpiresAtas the access token's expiry and say so innote: an expired access token there is not by itself a reason to log in again. - A sub-account profile reports its parent's
expiresAtandparent, never an expiry or token of its own. - These fields are derived, never stored in the profile document. They MUST NOT carry a token, a refresh token or a session fingerprint.
9. Re-authentication
A conforming host SHOULD offer a verb that logs a profile's parent account in
again. Through a projection with a terminal it is auth reauth <profile|parent>
(the reference CLI also takes --check, read-only, and --json). A projection
with no terminal (MCP, HTTP) MUST NOT run an interactive login: it returns the
command to run (the command of section 10) instead.
- The target is a profile id, or a bare parent (a credential source name or
an alias of it). A profile resolves to its parent through its
source; a profile that holds a stored key (credentialRef) has no login to redo, and the verb MUST say so and exit non-zero. - Per-source adapter. Each credential source supplies one small adapter:
read-only
inspectof the parent (id, label, whether a login is stored, expiry), a loginplan(a command to run, or manual instructions), and averifyrun after the login. Adding a source is adding an adapter; no other part of the host changes. - The login stays interactive; the rest is automated. The host MUST run the provider's own login with the terminal attached, and MUST do the before and after reads, the verification and the report itself. Where the provider's client has no login command that can be driven (the plan is manual), the host MUST print what to run and, with no terminal, exit with a distinct non-zero status rather than claim success.
- Verify the expected account. After the login the host MUST verify that the account now stored is the one that was expected: for a sub-account profile, that the stored login owns the pinned sub-account and that the provider accepts its session; where a login existed before, that it is the same parent account. When there was no earlier login to compare with, the host MUST state that only ownership could be checked.
- Leave other accounts alone. The login MUST NOT leave other stored accounts broken. The host MUST check that the other stored logins are unchanged, and report any that the login replaced or removed.
- Do not flip the active account silently. If the login moved the provider's own active account, the host MUST report it as a side effect, and MUST NOT undo it or change it on its own. Because resolution does not depend on it (section 7), the report states that no profile was affected.
- Honest report. The result is a verification with a
status(verified,failed,unverified) and four lists:checked(tested and passed),notChecked(what could not be tested, and why; for instance that the provider accepts the new login when the host has no way to exercise it),problems(tested and failed; non-empty meansfailed) andsideEffects. A host MUST NOT reportverifiedfor a check it did not run. The report MUST NOT carry a token or a session fingerprint. - The report lists the profiles that share the parent. For a source whose parent owns sub-accounts, it also states that one re-login fixes every sub-account profile under the parent.
Reference sources and their login: opencode-console runs the console login
(full verification, including sub-account ownership); claude-code-oauth,
codex delegate to the harness's own login command; gemini has no login
command and is manual.
10. The "log in again" error
When a spawn fails because the owning parent's session is expired,
missing, or rejected by the provider, the refusal MUST name the command that
fixes it, in its message, and MUST carry it as data:
interface ReauthHint {
command: string // e.g. "agentproto auth reauth <profile>"
source: string // the credential source of the parent
reason: "expired" | "missing" | "rejected"
profile?: string // the profile that needed the login
parent?: { id?: string; label?: string; expiredAt?: number } // epoch ms
}carried as details.reauth of the host's existing credential-unresolved
refusal (the reference implementation keeps its auth_source_unresolved
code and adds details.reauth; no new code is introduced). A bare provider
status (a 401 or 403) MUST NOT be the whole error. A failure that is not a
login problem (a provider outage, a network error) MUST NOT carry a hint. The
hint MUST NOT carry a token.
Rationale
Why a primitive and not a field of AIP-46. Sessions are not the only consumer: quota (AIP-67) reads per profile, spend caps aggregate per profile across sessions, and policy needs a resource to attach to. A session refers to a profile; it does not contain one.
Why endpoint and not provider. AIP-46's first draft used
provider. In practice the party that bills (a gateway, a subscription)
is often not the model builder, and every eligibility bug seen in the
reference implementation came from conflating the two.
Why model allow-lists are policy. An allow-list on a key is an access rule on a resource. Expressing it as a profile field gave the implementation a second, weaker access engine (no deny, no audit record, no delegation ceiling). AIP-38 already has all three.
Why re-login is per parent. A token authenticates a person to a provider; the sub-accounts (organizations, workspaces) are things that person belongs to. Modeling the login on the sub-account makes the same login expire many times over and makes "switch workspace" look like "sign in again". With the login on the parent, expiry has one owner, one verb fixes all of its profiles, and resolution can pick the right login by ownership instead of trusting whatever the provider's client had active last.
Why verification reports what it did not check. A re-login that cannot
tell whether the provider accepts the new session, or which account was
meant, is still useful, but only if it says so. A fixed vocabulary
(checked, notChecked, problems, sideEffects) keeps a green result from
meaning more than it proved.
Why no secret in the document. Profiles are listed, diffed, shown in pickers and sent to other processes. The only safe design is one where the document never had the secret to leak.
Backward Compatibility
- AIP-46 §Access profile's
authProfiles[]entries map one to one:idunchanged,providerbecomesendpoint,auth(an AIP-29 auth ref) becomes thecredentialReforsourcethe host resolves from it,subscriptionunchanged. AIP-46 will point to this AIP for the document and keep the amortisation formula. - AIP-67's
QuotaProfileprojection (profileRef,endpoint,method,credentialRef) is a subset of this document; nothing changes there. - A host whose profiles have no
policybehaves as before: the subject policy alone decides. - The reference implementation's
modelsandcostBudgetfields keep working as host short forms, evaluated as AIP-38 grants and limits. - Sections 7 to 10 add no field to the stored document (
expiresAt,stateandparentare derived on read) and no new refusal code. A host that does not implement them keeps its current behavior; a client that ignoresdetails.reauthsees the same error code as before.
Security Considerations
- Credential isolation. Section 1 forbids credential material in the document; section 5 forbids it in reads, logs and errors. A fingerprint lets a user tell two keys apart without either being revealed.
- No silent substitution. Section 2 forbids replacing an ineligible named profile with another one. Billing a different account than the one the user named is the most expensive failure this AIP can cause.
- Delegation ceiling. A child session cannot reach a parent's paid account unless the policy grants it; spawning is not a way to borrow a credential.
- Imported credentials. A host that discovers credentials (a harness's login, environment variables) MUST ask before creating a profile from them, and MUST NOT copy the secret out of its original store without that consent.
- No credential in expiry, reauth or the hint. The fields of section 8, the report of section 9 and the hint of section 10 are all derived from the parent's state. They MUST NOT carry a token, a refresh token or a session fingerprint; a host fingerprints a session only to detect that a login replaced it, and never emits the digest.
- Resolve by ownership. Resolving a sub-account profile through the provider's active account (section 7) can present one account's session for another account's organization. Resolution by the owning parent, with refusal instead of fallback, is what keeps a spawn from billing or acting as an account the user did not name.
- The interactive login is the provider's. A host runs the provider's own login with the terminal attached and never reads or relays the credential the user types; it reads the stored result afterwards, read-only, to verify.
- Sub-account identifiers can be sensitive (organization ids). Hosts SHOULD treat them like profile metadata, visible to the user only.
Reference Implementation
@agentproto/auth (agentproto/ts): profile-types.ts (AuthProfile,
ModelCuration, CostBudget, SubaccountPin), profile-store.ts
(~/.agentproto/auth-profiles.json), eligibility.ts
(eligibleProfiles, methodsPresentable), subaccounts.ts, and reauth.ts
(ReauthAdapter and its registry, deriveAuthState, profileAuthStatus,
AuthReauthRequiredError, ReauthHint). Per-source adapters live next to the
source: @agentproto/adapter-opencode (reauth.ts, full verification) and
@agentproto/cli (reauth/: Claude Code, Codex, Gemini). The CLI verb is
agentproto auth reauth; expiry shows in auth profile list and auth status.
Not yet in the reference implementation: an MCP or HTTP projection of the
verb, and the expiry fields on the MCP auth_profile_list read. The models
and costBudget short forms are evaluated outside AIP-38 today; moving them
onto the AIP-38 evaluator is follow-up work tracked with the AIP-38
amendment.
Open Questions
- Presentable methods in AIP-45. Eligibility rule 3 needs each harness
to declare which methods it can present per route. The reference
implementation projects this from the harness package; AIP-45 has no
field for it. Proposed in
agentproto/agentproto#98:
an AIP-45
auth.methods: { [route]: method[] }block, with the reserved route keydefaultfor the harness's own route. - AIP-19 access grants. AIP-19 has its own
accessgrant list (role, user, tool, workflow, workspace). It predates AIP-38 and overlaps it. Out of scope here; worth aligning separately. - A remote projection of
reauth. Section 9 says a terminal-less projection returns the command instead of running it. Whether a host should also offer an out-of-band way to complete a browser sign-in for a remote operator (a link, a device code) is left open. - Expiry for sources with no readable expiry. Section 8 reports
unknown. Whether a host should probe the provider to turnunknownintookorexpired(at the cost of a network call on every list) is left open. - Default profile order. Section 2 lets a host pick a profile when none
is named. Should the order be a field here (
priority), or stay in the session config (AIP-46 amendment) as an ordered fallback? The current draft leaves it to the session config.
See also
- AIP-19 SECRETS: where the credential lives
- AIP-29 CLI: how a harness logs in
- AIP-38 POLICY: the rules attached to a profile
- AIP-39 ACTION:
auth-profile:use,model:invoke - AIP-46 AGENT-SESSIONS: session binding, amortisation, session config (informative: AIP-46 depends on this AIP, not the reverse)
- AIP-67 QUOTA: headroom per profile
Resources
Supporting artifacts for AIP-69. Links open the file on GitHub — markdown and JSON render natively in GitHub's viewer. Browse the full resource tree →
AIP-68: CLERK (clerk/v1): out-of-band session clerks (STEWARD.md, SECRETARY.md): triage and memory lenses
Names the clerk, an out-of-band process that watches daemon sessions' transcripts and lifecycle events and maintains durable STATE about them without ever waking the watched session, as one workspace of two composable doctypes: STEWARD.md (`agentsteward/v1`), the session-triage profile that classifies sessions into verdicts (done / abandoned / blocked / needs-input / active) and applies AIP-46 outcomes (mark-complete, mark-failed, close-abandoned...) under an origin policy that never closes a human's session; and SECRETARY.md (`agentsecretary/v1`), the memory-secretary profile that runs LLM distill lenses (session, project, user, company) over raw transcripts toward a two-level store (per-agent local, promoted shared), with per-source cursors, anti-rebound debounces, dedup by origin, and free-tier model budgets.
AIP-70: GLOSSARY (glossary/v1): canonical names and vocabulary for every AIP
One name per AIP, used the same way in its title, its schema ids, its package, its define function and its tool names; one meaning per term across the specs and the reference implementation. Fixes the naming rules, the names.json registry and the ratchet check that enforces it, the vocabulary with the senses each term must not take, and the deprecated aliases with their replacements.