Authentication
Hyponema uses different credentials for different boundaries. Keep the boundary clear.
Workspace API keys
Section titled “Workspace API keys”Workspace API keys are managed in Settings under API keys. Use them from trusted backend services only. Do not place them in:
- Browser code.
- Widget snippets.
- Mobile apps.
- Public repositories.
- Customer-visible logs.
Rotate keys when team membership, deployment ownership, or incident response requires it.
Workspace API keys are bound to one workspace. They can call frontend-parity workspace API routes for that workspace when the key has the required scope. They cannot manage API keys, billing, members, provider credentials, SSO, privacy controls, compliance exports, User erasure, recording retrieval, workspace profile images, or WhatsApp account and number administration.
Scopes
Section titled “Scopes”Use the narrowest scope that covers the backend task. workspace:read includes non-sensitive granular read scopes. workspace:write includes workspace:read and non-sensitive granular write scopes. Sensitive memory, collected data, post-session records, and webhook administration must be granted explicitly. The current webhook endpoint management and delivery-history API-key surface requires webhooks:admin; webhooks:read and webhooks:write are not sufficient for those routes.
| Surface | Read scope | Write scope |
|---|---|---|
| Workspace settings | workspaces:read | workspaces:write |
| Agents and playground rendering | agents:read | agents:write |
| Agent configuration and templates | personas:read | personas:write |
| Knowledge sources and agent knowledge attachments | knowledge:read | knowledge:write |
| Integrations, integration providers, and post-session runners | integrations:read | integrations:write |
| Tests, datasets, scorers, evaluation, data collection, and online scorer rules | tests:read | tests:write |
| Phone numbers and phone recording settings | phone_numbers:read | phone_numbers:write |
| Schedules | schedules:read | schedules:write |
| Voice bookmarks, providers, and listening profiles | voice:read | voice:write |
| User profile fields and variable resolvers | user_profile_fields:read | user_profile_fields:write |
| Memory | memory:read; memory_sensitive:read is explicit grant only | memory:write |
| Collected data and post-session records | collected_data:read and post_session_records:read are explicit grant only | none |
| Users | users:read | users:write |
| Conversations | conversations:read | none |
| Sessions | sessions:read | sessions:write |
| Observability | observability:read | observability:write |
| Webhook endpoint management, delivery history, and secret rotation | webhooks:admin is explicit grant only | webhooks:admin is explicit grant only |
| Audit log | audit_log:read | none |
If a request reaches a supported API-key route without the required scope, Hyponema returns 403 with a missing-scope error. If the route is dashboard-only, Hyponema returns 403 with a dashboard-user-required error.
Provider credentials
Section titled “Provider credentials”Provider credentials are managed in Settings under Providers. These credentials let Hyponema connect to model, speech, telephony, messaging, or related providers for the workspace.
Provider keys are not the same as workspace API keys. Do not paste provider credentials into agent prompts or client-side code.
Browser-facing values
Section titled “Browser-facing values”Browser clients should use signed or otherwise limited values generated for a specific session or channel. Generate those values from your backend or copy them from the current dashboard channel setup when the UI provides them.
Access troubleshooting
Section titled “Access troubleshooting”If authentication fails, check:
- The request is coming from a trusted backend.
- The workspace API key belongs to the selected workspace.
- The key has not been revoked or rotated.
- The channel value has not expired.
- The member configuring the key has the required workspace permission.