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

# Authentication

> Planned authentication, scopes, and secret handling for the Woes public API.

The public API will require authenticated requests for workspace data and operational actions. Authentication should be designed around least privilege and clear separation between server credentials, browser-safe widget keys, and third-party API credentials used for testing.

## Credential model

| Credential                  | Where it lives                               | Purpose                                                |
| --------------------------- | -------------------------------------------- | ------------------------------------------------------ |
| Server API credential       | Your server or secret manager.               | Authenticated Woes public API requests.                |
| Widget public key           | Browser code.                                | Routes widget traffic to the correct workspace.        |
| Conversation history secret | Customer browser state for one conversation. | Authorizes loading that conversation's widget history. |
| API test credential         | Woes credential storage.                     | Lets Woes run guarded live API tests against your API. |

<Warning>
  A widget public key is not an API credential. It can be visible in browser code, but it must not unlock authenticated workspace API access.
</Warning>

## Planned capabilities

<CardGroup cols={2}>
  <Card title="Server credentials" icon="key">
    API keys or bearer tokens for server-to-server integration.
  </Card>

  <Card title="Scopes" icon="list-checks">
    Read and write boundaries for resources such as conversations, customers, and sources.
  </Card>

  <Card title="Rotation" icon="refresh-cw">
    Create, revoke, and rotate credentials without exposing old secrets.
  </Card>

  <Card title="Usage metadata" icon="activity">
    Audit-friendly metadata for credential usage without leaking the credential itself.
  </Card>
</CardGroup>

## Expected scope categories

Final scope names are not published yet. Expected categories include:

* Workspace settings.
* Conversations.
* Messages.
* Customers.
* API Context sources.
* Agent and Lab data.
* Channels.
* Webhooks.

## Integration expectations

<Steps>
  <Step title="Create a scoped credential">
    Choose only the categories the integration needs.
  </Step>

  <Step title="Store it securely">
    Keep server credentials in a secret manager, not in browser code or client-side config.
  </Step>

  <Step title="Call authenticated APIs">
    Send the credential from your server when endpoint-level docs are available.
  </Step>

  <Step title="Rotate when needed">
    Rotate credentials after suspected exposure, team changes, or integration changes.
  </Step>
</Steps>

## Security expectations

* Do not expose server keys in browser code.
* Use the narrowest scope that supports your integration.
* Treat logs as sensitive if they include authorization headers.
* Rotate credentials after suspected exposure.
* Keep widget keys and server credentials conceptually separate.