Connecting via OAuth 2.0

For browser-based clients like claude.ai, Torch & Lily supports OAuth 2.0 with PKCE.

Discovery

Authorization server metadata is published at:

https://api.torchandlily.com/.well-known/oauth-authorization-server

Compatible MCP clients will discover the endpoints automatically — no manual configuration is required.

The protected-resource document, which tells MCP clients which authorization server protects this resource, lives at:

https://api.torchandlily.com/.well-known/oauth-protected-resource

And the public signing keys (JWKS) for verifying access tokens:

https://api.torchandlily.com/.well-known/jwks.json

Manual flow

If you are integrating a custom client, the flow is the standard RFC 6749 + RFC 7636 dance:

1. Register your client (or use a pre-registered one):

   POST https://api.torchandlily.com/oauth/register
   Content-Type: application/json
   
   {
     "redirect_uris": ["https://your.app/cb"],
     "client_name": "My MCP Client",
     "grant_types": ["authorization_code", "refresh_token"],
     "token_endpoint_auth_method": "none"
   }

2. Authorize — redirect the user’s browser to:

   https://api.torchandlily.com/oauth/authorize
     ?response_type=code
     &client_id=<client_id>
     &redirect_uri=<your-redirect>
     &code_challenge=<S256(verifier)>
     &code_challenge_method=S256
     &state=<opaque>
     &scope=mcp:read

   The user reviews and approves access on a Torch & Lily–hosted consent page; the browser is then redirected back to your redirect_uri with ?code=...&state=....

3. Exchange the auth code for tokens:

   POST https://api.torchandlily.com/oauth/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code
   &code=<received-code>
   &redirect_uri=<same-as-above>
   &client_id=<client_id>
   &code_verifier=<original-verifier>

   Response: access_token, refresh_token, token_type=Bearer, expires_in=3600.

4. Call the MCP server:

   POST https://api.torchandlily.com/mcp
   Authorization: Bearer <access_token>

5. Refresh when the access token nears expiry:

   POST https://api.torchandlily.com/oauth/token
   
   grant_type=refresh_token
   &refresh_token=<current-refresh>
   &client_id=<client_id>

   The old refresh token is revoked; a new pair is issued.

Scopes

Scope	Permission
mcp:read	Read access to all read-only MCP tools across Veritas, Devotio, Tempus, and Corpus

Communio (the write engine for intercessory prayer) is excluded from OAuth — it uses a separate tenant key model.

Token lifetimes

• Access token: 1 hour, RS256-signed JWT. Validated statelessly via the public JWKS — no DB lookup per request.
• Refresh token: 30 days, opaque, rotated on every use. Reuse of an already-redeemed refresh token revokes the entire rotation chain as a security measure (RFC 6749 §10.4).

Revocation

Revoke a refresh token at any time:

POST https://api.torchandlily.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=<refresh_token>

Per RFC 7009, this endpoint is idempotent and always returns 200 OK — even if the token is unknown.

You can also manage and revoke active connections from your dashboard.