API Keys
Create and manage API keys for external integrations.
API Keys
API keys allow external systems to authenticate with the VayaFlow API without requiring a user session.
Creating an API Key
- Navigate to Settings in the sidebar
- Go to the API Keys section
- Click Generate API Key
- Copy the key — it will only be shown once
Using an API Key
Include the key in the X-API-Key header of your HTTP requests:
curl -X GET https://api.vayaflow.com/api/v1/playbooks \
-H "X-API-Key: your_api_key"Security Best Practices
- Store API keys securely — never commit them to source control
- Rotate keys periodically
- Use separate keys for different integrations so you can revoke individually
- Monitor the activity log for unexpected API usage
Scopes
Every key carries a list of scopes, chosen when the key is generated. A request is allowed only when the key holds the scope for that route's area and access level. Reads (GET) need the :read scope; everything else needs :write. A request outside the key's scopes returns 403 with error.code set to INSUFFICIENT_SCOPE and error.details.required naming the missing scope.
| Area | Read | Write | Covers |
|---|---|---|---|
| Contacts | contacts:read | contacts:write | contacts, views, imports, callbacks, outreach runs, recovery |
| Playbooks | playbooks:read | playbooks:write | playbooks, questionnaires, goals, sequences, delivery endpoints, sources, field library |
| Agents and channels | agents:read | agents:write | agents, tools, playground, knowledge bases, phone numbers, SMS and voice actions |
| Conversations | conversations:read | conversations:write | conversation history |
| Files | files:read | files:write | file library |
| E-signing | esign:read | esign:write | sign templates, submissions, notification settings |
| Intake flows | intake:read | intake:write | intake flows, brands, domains |
| Workflows | workflows:read | workflows:write | workflow definitions and executions |
| Settings and team | settings:read | settings:write | organization, team, API keys, connections and secrets |
| Analytics and usage | analytics:read | none | analytics, dashboard, usage, activity log (read-only) |
Keys created before scopes were enforced were granted full access; narrow them by generating a new key with only the scopes the integration needs and revoking the old one.