API guide
Connect another workspace with OAuth
Register your application
Register exact redirect URLs in the developer dashboard. Send the person to /oauth/authorize with client_id, redirect_uri, response_type=code, scope, state, code_challenge and code_challenge_method=S256. Add mode=test for a sandbox connection or mode=live for live access. Omitting mode selects live for compatibility. The consent page shows the selected mode; tokens and refreshes remain bound to that mode. Check livemode in token responses and /me. Generate a fresh high-entropy verifier and state for every authorization attempt.
Verify state on return before exchanging the code at /oauth/token. Send the original code_verifier and redirect_uri. Codes are single-use. Keep client secrets on your server.
Refresh and disconnect
Access tokens last one hour. Refresh tokens rotate on use; replace the stored refresh token atomically and serialize refreshes for one connection. Reuse of an old refresh token revokes the connection.
Use /oauth/revoke or the dashboard to disconnect. Treat revoked authorization as a request to stop: do not repeatedly prompt or silently reconnect a workspace.