Key Takeaway
AI auth models must account for cost implications of each request, making usage-based access control a first-class concern alongside traditional role-based permissions.
When to Use This Template
Use this ADR when designing authentication and authorization for AI-powered features, migrating between auth models (e.g., from platform-managed to BYOA keys), or adding usage-based access tiers to existing AI features. AI features carry direct per-request costs that traditional auth models do not account for, making this a distinct architectural decision from general application auth.
ADR Template
# ADR: Auth Model for AI Features
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
## Date
YYYY-MM-DD
## Decision Makers
- [Name, Role]
## Context
### User Types
- Internal users: [roles and expected usage patterns]
- External users: [roles and expected usage patterns]
- API consumers: [programmatic access requirements]
### Cost Model
- Average cost per AI request: [e.g., "$0.02 per request"]
- Monthly cost ceiling per user: [e.g., "$50/month for free tier"]
- Abuse risk profile: [e.g., "API access enables automated high-volume usage"]
### Existing Infrastructure
- Current auth system: [e.g., "Clerk for user auth, no API key management"]
- Current rate limiting: [e.g., "none" or "100 requests/minute per user"]
- Compliance requirements: [e.g., "SOC 2 key rotation requirements"]
## Options Considered
| Criterion | Platform Keys | BYOA Keys | OAuth Scopes | Usage Tiers |
|-----------|--------------|-----------|--------------|-------------|
| User friction | Low | Medium | Low | Low |
| Cost exposure to platform | Full | None | Full | Capped |
| Key security burden | Platform | User | Platform | Platform |
| Usage tracking | Built-in | Requires proxy | Built-in | Built-in |
| Rate limiting | Platform-managed | Provider-managed | Platform-managed | Platform-managed |
## Decision
We will use [auth model] because [rationale].
### Implementation Plan
1. Key management: [storage, rotation, encryption approach]
2. Rate limiting: [limits by tier, enforcement mechanism]
3. Usage tracking: [how usage is measured and reported]
4. Abuse prevention: [circuit breakers, anomaly detection]
## Consequences
- User experience: [friction assessment for key setup, usage tracking UX]
- Cost exposure: [who bears inference costs under each scenario]
- Security posture: [key storage, rotation, breach response plan]
- Operational burden: [monitoring, support requests, key management]
## Review Trigger
- [ ] Security incident involving API keys
- [ ] User complaints about auth friction exceed [threshold]/month
- [ ] Cost overruns from abuse exceed [threshold]/month
- [ ] New compliance requirement introducedSection-by-Section Guidance
BYOA vs. Platform-Managed Keys
The choice between BYOA (Bring Your Own API Key) and platform-managed keys is the most consequential decision in this ADR. BYOA eliminates the platform's cost exposure entirely but adds user friction (key setup, provider account creation) and complicates usage tracking. Platform-managed keys offer a smoother user experience but require the platform to absorb or bill for inference costs. Hybrid approaches are possible: use platform keys for trial/free tiers and BYOA for production usage.
Rate Limiting Strategy
AI features require rate limiting at multiple levels: per-user request rate, per-user token consumption, and global cost circuit breakers. Request rate limits alone are insufficient because a single request can consume vastly different token counts depending on input length and model response. Implement token-based usage tracking alongside request rate limiting for complete cost control.
If using BYOA keys, encrypt them at rest with AES-256-GCM and store only the last four characters in plaintext for UI display. Never log full API keys, and implement automatic key validation on a schedule to detect revoked keys before users encounter errors.
Do not store API keys in browser localStorage or session storage. Even with BYOA, keys should be sent to the server once, encrypted, and stored server-side. Client-side key storage is vulnerable to XSS attacks and browser extensions.
Version History
1.0.0 · 2026-03-01
- • Initial ADR template for AI auth model