Skip to main content
Spreadsheet clients use a user-approved session bound to a specific document. Server integrations use service-account API keys instead.

​
Start a document-bound challenge

Generate a fresh secret verifier in the client. Hash it with SHA-256 and encode the digest as base64url to obtain the code challenge. Keep the verifier private. Send POST /api/v2/metrics/client-auth/challenges with:
  • clientKind: google_sheets or excel.
  • audience: chatobserver-metrics-sheets or chatobserver-metrics-excel for the corresponding client.
  • documentReferenceHash: the SHA-256 reference for the document.
  • hostUserReferenceHash: the host-user reference hash, or null.
  • codeChallenge: the encoded verifier hash.
The response supplies the challenge ID, a private poll secret, the user code, an authorisation URL, the polling interval, and expiry. Open the supplied authorisation URL so the user can approve the workspace connection. The challenge expires after ten minutes.

​
Exchange the approved challenge

Send POST /api/v2/metrics/client-auth/challenges/{challengeId}/exchange with the matching audience, poll secret, and original codeVerifier. While approval is pending, the API returns a retryable 412 with a retry delay. Follow that delay and stop at expiry or denial. After approval, the exchange returns a session token, workspace and actor identifiers, client kind, scopes, and expiry. The challenge is consumed by a successful exchange. Store the session securely and start a new authorisation when it expires.

​
Make client requests

For /api/v2/metrics/client/ endpoints, include:
The audience and document reference must match the authorised session. Sessions carry client:read, client:write, and client:execute capabilities and depend on the user’s active workspace membership and Data access. Use DELETE /api/v2/metrics/client/session to disconnect the session. For spreadsheet writes, follow the claim, checkpoint, and commit operations in the API reference.