trello-plugin/docs/backend/001_trello_auth_spec.md

Trello Plugin — Authentication & Connection

Feature: US: Authenticate and Connect to Trello Account Issue: #1 Branch: feature/trello-auth Doc: 001

Overview

This feature provides the authentication layer for the Trello plugin. Users configure their Trello credentials via environment variables (TRELLO_API_KEY and TRELLO_TOKEN), and the plugin exposes tools to verify credentials, list accessible boards, and disconnect.

Design Decisions

• No interactive credential input — The Hermes Agent has no UI for prompting users. Credentials are set in the profile's .env or config.yaml as environment variables, which is the standard Hermes pattern.
• Trello uses API Key + Token auth — Trello's API requires an API key (identifies the application) and a token (user-specific authorization). Both are required for any API call.
• One client class — All Trello API interactions go through a single TrelloClient class to centralize auth, base URL, and error handling. Future features (boards, lists, cards) will extend this same client.

Environment Variables

Variable	Required	Description
TRELLO_API_KEY	Yes	Trello API application key
TRELLO_TOKEN	Yes	Trello user authorization token

Tools Exposed

1. trello_verify_credentials

Verifies that TRELLO_API_KEY and TRELLO_TOKEN are set and the Trello API responds successfully.

Parameters: None

Returns:

{
  "success": true,
  "message": "✓ Trello credentials verified successfully (authenticated as user@example.com)"
}

On failure:

{
  "success": false,
  "message": "✗ Trello authentication failed: invalid key"
}

2. trello_list_boards

Fetches and returns all Trello boards accessible to the authenticated user.

Parameters: None

Returns:

{
  "success": true,
  "boards": [
    {"id": "abc123", "name": "My Project Board", "url": "https://trello.com/b/abc123"},
    {"id": "def456", "name": "Personal Tasks", "url": "https://trello.com/b/def456"}
  ]
}

3. trello_disconnect

Clears the stored credentials from memory. Since credentials are stored in environment variables, the next tool call will automatically re-read them and reconnect. To fully disconnect, also unset TRELLO_API_KEY and TRELLO_TOKEN from the Hermes profile config.

Note: this does NOT revoke the Trello token — the user must invalidate it via Trello's settings if needed.

Parameters: None

Returns:

{
  "success": true,
  "message": "Trello credentials cleared from memory. Next tool call will re-read TRELLO_API_KEY and TRELLO_TOKEN from environment and reconnect automatically."
}

API Contract

Internal: TrelloClient

class TrelloClient:
    api_key: str
    token: str

    def __init__(self, api_key: str | None = None, token: str | None = None)

    def verify_credentials(self) -> dict
    def list_boards(self) -> list[dict]
    def disconnect(self) -> dict

The client uses TypedDict response contracts (SuccessResponse/ErrorResponse) with a TypeGuard helper _is_success() for type-safe narrowing. Internal helpers include _request(), _get(), _post(), _put(), _check_credentials(), and _handle_http_error().

Trello API Endpoints Used

Purpose	Method	Endpoint	Docs
Verify credentials	GET	/1/members/me	https://developer.atlassian.com/cloud/trello/rest/api-group-members/
List boards	GET	/1/members/me/boards	https://developer.atlassian.com/cloud/trello/rest/api-group-boards/

Error Handling

• Missing env vars → return {"success": false, "message": "TRELLO_API_KEY and TRELLO_TOKEN must be set"} with env var name
• Network errors → catch requests.exceptions.RequestException and return descriptive message
• Auth failures (401/403) → clear message about invalid credentials
• Rate limiting → Trello returns 429; surface the retry-after header

Testing

• Unit tests with mocked HTTP responses
• Test all error paths: missing creds, invalid creds, network error, rate limit
• Test successful verification via mock that returns member info
• Test board listing with mock JSON response