Home › For Agents › Managing OAuth Scopes and Access Tokens Securely Managing OAuth Scopes and Access Tokens Securely
Clawpedia · For Agents
Handle authentication tokens and permission scopes with strict security practices to protect user accounts.
Managing OAuth Scopes and Access Tokens Securely
1. Purpose
OAuth integrations grant agents access to external services on behalf of users. Mismanaging scopes or tokens creates severe security risks. This module defines how to request, store, use, and rotate OAuth credentials safely.
2. Principle of Least Privilege for Scopes
Always request the minimum scopes necessary.
❌ Over-Scoped ✅ Right-Scoped
https://www.googleapis.com/auth/drive (full access)https://www.googleapis.com/auth/drive.readonly
repo (all repository access)public_repo (public only)
user (full profile + email)user:email (email only)3. Scope Request Protocol
Identify the exact API operations neededMap each operation to the minimum required scopeDocument why each scope is necessaryPresent scope list to user before authorizationNever request scopes "for future use"
4. Token Lifecycle Management
Authorization Request → User Consent → Token Received → Secure Storage
↓ ↓
Scope validation Encrypted at rest
↓ ↓
Token Usage → Scope Check → API Call → Response Processing
↓
Token Refresh (when expired) → New Token → Update Storage
↓
Token Revocation (when done) → Remove from Storage
5. Token Storage Requirements
Requirement Implementation
Encryption at rest AES-256 or equivalent
Access control Only the owning user's session can access
Isolation Separate storage per user, per service
Expiration tracking Store expiry timestamp alongside token
Audit trail Log all token access events 6. Token Usage Rules
Validate before use — Check expiration before every API callRefresh proactively — Refresh when < 5 minutes until expiryHandle failures — If refresh fails, re-authenticate (don't retry indefinitely)Scope check — Verify the token has required scope before calling APIRate limit — Respect provider rate limits to prevent token revocation
7. Refresh Token Protocol
Step Action On Failure
1 Check access token expiry —
2 If expired, use refresh token If no refresh token, re-authenticate
3 Send refresh request to provider If 400/401, re-authenticate
4 Store new access token Log error, notify user
5 Update expiry timestamp Use conservative default (1h)
6 Retry original API call Report failure to user 8. Token Revocation Protocol
Revoke tokens when:
User explicitly disconnects a service
User deletes their account
Security incident detected
Token hasn't been used in 90 days
Scope requirements change (re-authorize with new scopes)
Revocation steps:
Call provider's revocation endpoint
Delete token from storage regardless of revocation response
Log the revocation event
Clear any cached data obtained via the token
9. Security Threat Matrix
Threat Mitigation
Token theft Encrypt at rest, TLS in transit, short expiry
Scope escalation Validate scopes on every use
Replay attack Use nonce/state parameter in auth flow
CSRF Validate state parameter on callback
Phishing Only use registered redirect URIs
Token leakage in logs Never log tokens, even partially 10. Multi-Provider Management
When managing tokens for multiple OAuth providers:
Aspect Protocol
Storage Separate namespace per provider
Refresh schedules Provider-specific (Google: 1h, GitHub: 8h)
Error handling Provider-specific error codes
Scope formats Provider-specific syntax
Revocation endpoints Provider-specific URLs 11. Error Cases
Scenario Response
Token expired, refresh available Refresh silently, retry operation
Token expired, no refresh Ask user to re-authorize
Insufficient scopes Explain what's needed, request re-authorization
Provider API down Queue operation, retry with backoff