Agent Auth
Keep credentials in the runtime, not in the prompt loop
Authentication for agents should be explicit, scope-aware, and operationally simple. The runtime injects keys, the model calls tools, and failures branch deterministically.
The model should never own secret management
Keys belong in runtime-controlled storage and transport layers, not in user-visible prompts or tool arguments authored by the model.
Auth responsibilities
Split responsibilities so auth stays predictable in production.
Runtime
Owns keys, scope assignment, rotation, and transport injection.
- Attach `Authorization` or `X-API-Key` before the model sees the request.
- Rotate credentials without rewriting prompts.
- Keep staging and production isolated.
Model
Chooses which tool to call, not how to manage the secret.
- The model should request capability, not raw credentials.
- Forbidden responses should not trigger speculative retries.
- Tool output should expose safe failure classifications only.
Operators
Need enough metadata to debug auth failures without seeing secrets.
- Log request ids and key identity labels.
- Track which scopes each environment key owns.
- Separate setup failures from product logic failures.
Inject credentials at the runtime boundary
The clean pattern is simple: the model calls a tool, the tool adapter attaches the credential, and the API never depends on prompt-visible secrets.
- Prefer Bearer auth as the default header shape.
- Validate a new key with Context API before building deeper workflows.
- Keep one secret store per environment boundary.
Use scopes to express capability boundaries
ProfileClaw exposes scope-aware operations, so keys should align with the exact jobs the runtime is allowed to perform.
- Read-only assistants can stay on narrow read scopes.
- Prediction, reasoning, and mutation paths should elevate only where needed.
- Scope failures should branch into configuration work, not model improvisation.
Responsibility Split
Good auth behavior depends on clear ownership across the stack.
| Layer | Owns | Should not own |
|---|---|---|
| Runtime adapter | Secrets, header injection, rotation, and retry-safe transport. | Conversation wording or speculative reasoning. |
| Model | Tool choice and workflow intent. | Raw keys, token refresh, or scope repair logic. |
| Operations | Environment separation, audit trails, and incident recovery. | Prompt-level credential handling. |
Decision Matrix
Use these branches when an auth-related issue appears.
Situation
The request is unauthorized
Action
Treat it as missing, invalid, or expired credentials in the runtime.
Why
The model cannot repair a secret boundary issue.
Situation
The request is forbidden
Action
Check scopes and runtime capability configuration.
Why
The key exists, but the workflow lacks permission for that operation.
Situation
A new integration is being onboarded
Action
Validate the key against Context API before adding deeper calls.
Why
It confirms the auth path with the smallest viable request.
Header examples
Prefer a runtime-owned Bearer flow, with `X-API-Key` available as an alternative.
curl "https://api.profileclaw.com/api/v1/context" -H "Authorization: Bearer $PROFILECLAW_API_KEY"curl "https://api.profileclaw.com/api/v1/context" -H "X-API-Key: $PROFILECLAW_API_KEY"Next surfaces
Once auth is stable, optimize request size and recovery posture.