> ## Documentation Index
> Fetch the complete documentation index at: https://chatobserver.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How do I authorise a spreadsheet client to use chatobserver data?

> Use the document-bound authorisation flow for Google Sheets and Excel clients without exposing workspace API keys.

Spreadsheet clients use a user-approved session bound to a specific document. Server integrations use [service-account API keys](/docs/developers/data-api) 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:

```text theme={null}
Authorization: Bearer <session token>
x-metrics-client-audience: <approved audience>
x-metrics-document-reference: <document reference hash>
```

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](/docs/api-reference/spreadsheet-clients).