Skip to content

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

PurposeURL
Discoveryhttps://api.treechat.com/.well-known/oauth-authorization-server
Authorizehttps://api.treechat.com/mcp/oauth/authorize
Tokenhttps://api.treechat.com/mcp/oauth/token
Revokehttps://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.

ScopeLets your appNeeded for
treechat:writePost and reply as the memberPOST /posts, GET /operations/{id}
uploads:writeUpload images, audio and video to the member’s accountPOST /uploads
treechat:readSee the member’s threads, including private onesGET /threads, GET /threads/{id}, GET /posts/{id}
account:readSee the member’s ID and usernameGET /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:

ParameterValue
response_typecode
client_idYour client ID
redirect_uriOne of your registered redirect URIs, exactly
scopeSpace-separated scopes
stateA random value you check on return
code_challengeBase64url SHA-256 of your verifier, no padding
code_challenge_methodS256 (required; plain is refused)
resourcehttps://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.

Terminal window
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/mcp

The response has access_token, refresh_token, expires_in (seconds) and scope.

Using the token

Send it on every API call:

Authorization: Bearer ACCESS_TOKEN

Cookies never authenticate API calls.

Refreshing tokens

Access tokens last 15 minutes. Before or after one expires, trade the refresh token for a new pair:

Terminal window
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:

Terminal window
curl -X POST https://api.treechat.com/mcp/oauth/revoke \
-u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
-d token=REFRESH_TOKEN

Members 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.