kingfisher/docs/REVOCATION_VERIFICATION_NOTES.md

Revocation Implementation Verification Notes

Common Patterns

Multi-Step Revocation Pattern

Most services require a 2-step process:

1. Step 1: List resources (keys/tokens) to extract the internal ID
2. Step 2: Delete using the extracted ID

Reason: Services don't accept the token string itself for deletion; they require an internal ID/key identifier.

Authentication Methods

• Bearer Token: SendGrid, Tailscale, NPM (most common)
• Basic Auth: Sumo Logic, Twilio
• HTTP Digest: MongoDB Atlas (unique)

Response Codes

• 204 No Content: Most common success response (SendGrid, MongoDB, Twilio, NPM, Sumo Logic, Tailscale for some endpoints)
• 200 OK: Tailscale (documented), some services with response bodies

Verification Process

Each service was verified by:

1. Searching official API documentation
2. Checking OpenAPI/Swagger specs where available
3. Verifying endpoint paths, HTTP methods, and response codes
4. Confirming authentication requirements
5. Testing JSONPath extraction patterns against documented response formats

Future Considerations

Services to Monitor

• Netlify: May add programmatic token management in future API versions
• ElevenLabs: May extend Service Accounts API to include key deletion
• Sourcegraph: May add GraphQL mutation for individual token deletion

Potential Issues

1. Multiple Tokens: Current implementations extract the "first" token from lists, which may not be correct if multiple active tokens exist
2. Rate Limiting: No rate limiting handling implemented in revocation flows
3. Partial Success: If Step 1 succeeds but Step 2 fails, the system doesn't retry
4. Token Identification: Services that don't return full token values in lists make it hard to identify the correct token

Recommendations

1. Before Using: Always verify you have only one active token for the service
2. Test in Development: Use non-production tokens to test revocation flows
3. Monitor API Changes: Service APIs may change; periodically verify endpoints still work
4. Check Documentation: Always consult the latest service documentation before revoking critical tokens
5. Consider Dry-Run: Implement a dry-run mode that shows what would be revoked without actually revoking

References

• Multi-Step Revocation Implementation
• Token Revocation Support Documentation
• Rules Documentation