Authentication
Treechat is a standard OAuth 2.0 authorization server. Apps use the authorization code flow with PKCE and authenticate to the token endpoint with their client ID and secret.
Endpoints
| Purpose | URL |
|---|---|
| Discovery | https://api.treechat.com/.well-known/oauth-authorization-server |
| Authorize | https://api.treechat.com/mcp/oauth/authorize |
| Token | https://api.treechat.com/mcp/oauth/token |
| Revoke | https://api.treechat.com/mcp/oauth/revoke |
Read the discovery document at startup rather than hard-coding the others.
Permissions (scopes)
Ask only for what your app uses. The member sees each one on the approval page.
| Scope | Lets your app | Needed for |
|---|---|---|
treechat:write | Post and reply as the member | POST /posts, GET /operations/{id} |
uploads:write | Upload images, audio and video to the member’s account | POST /uploads |
treechat:read | See the member’s threads, including private ones | GET /threads, GET /threads/{id}, GET /posts/{id} |
account:read | See the member’s ID and username | GET /me |
Apps registered through App Connect can’t request generation or billing scopes, and they can’t spend the member’s money.
Authorization request
Send the browser to the authorize endpoint with:
| Parameter | Value |
|---|---|
response_type | code |
client_id | Your client ID |
redirect_uri | One of your registered redirect URIs, exactly |
scope | Space-separated scopes |
state | A random value you check on return |
code_challenge | Base64url SHA-256 of your verifier, no padding |
code_challenge_method | S256 (required; plain is refused) |
resource | https://api.treechat.com/mcp |
On success Treechat redirects to redirect_uri?code=…&state=…. If the member declines, it redirects with error=access_denied.
Token request
POST form-encoded to the token endpoint. Authenticate with HTTP Basic (client_id:client_secret), or send client_id and client_secret in the body.
curl -X POST https://api.treechat.com/mcp/oauth/token \ -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \ -d grant_type=authorization_code \ -d code=CODE \ -d redirect_uri=https://yourapp.com/auth/treechat/callback \ -d code_verifier=VERIFIER \ -d resource=https://api.treechat.com/mcpThe response has access_token, refresh_token, expires_in (seconds) and scope.
Using the token
Send it on every API call:
Authorization: Bearer ACCESS_TOKENCookies never authenticate API calls.
Refreshing tokens
Access tokens last 15 minutes. Before or after one expires, trade the refresh token for a new pair:
curl -X POST https://api.treechat.com/mcp/oauth/token \ -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \ -d grant_type=refresh_token \ -d refresh_token=REFRESH_TOKEN- Each refresh token works once. Store the new one from every response.
- If two requests refresh at the same time, only one succeeds. Refresh from one place per member.
- A connection that isn’t used for 30 days expires. The refresh then fails with
invalid_grant, and the member has to connect again.
Revoking and disconnects
To sign a member out of your app, revoke the refresh token:
curl -X POST https://api.treechat.com/mcp/oauth/revoke \ -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \ -d token=REFRESH_TOKENMembers can also disconnect your app from Connected apps in Treechat. That revokes every token and pending code for your app at once. Your next call gets 401; send the member through the authorization flow again.
Client secrets
- The secret is shown once when you register or rotate it. Treechat stores only a hash.
- Rotate it from your app’s page if it leaks. The old secret stops working immediately.
- Never put the secret in a browser or mobile app.
Suspension
Treechat can suspend an app that misbehaves. While suspended, every call made for anyone other than the app’s developer returns 403 with code app_suspended.