Skip to main content
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

CredentialWhere it livesPurpose
Server API credentialYour server or secret manager.Authenticated Woes public API requests.
Widget public keyBrowser code.Routes widget traffic to the correct workspace.
Conversation history secretCustomer browser state for one conversation.Authorizes loading that conversation’s widget history.
API test credentialWoes credential storage.Lets Woes run guarded live API tests against your API.
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.

​
Planned capabilities

Server credentials

API keys or bearer tokens for server-to-server integration.

Scopes

Read and write boundaries for resources such as conversations, customers, and sources.

Rotation

Create, revoke, and rotate credentials without exposing old secrets.

Usage metadata

Audit-friendly metadata for credential usage without leaking the credential itself.

​
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

1

Create a scoped credential

Choose only the categories the integration needs.
2

Store it securely

Keep server credentials in a secret manager, not in browser code or client-side config.
3

Call authenticated APIs

Send the credential from your server when endpoint-level docs are available.
4

Rotate when needed

Rotate credentials after suspected exposure, team changes, or integration changes.

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