API reference / Get started
Authentication and permissions
Use scoped API keys for REST integrations and OAuth for MCP.
| Interface | Authentication | Where to start |
|---|---|---|
REST: /api/v1/* | Vendita API key in the Bearer header | API quick start |
MCP: /api/mcp | OAuth sign-in and user approval | MCP quick start |
The OpenAPI document is public. Protected REST operations require a key.
Authorization: Bearer vk_live_YOUR_KEYvk_live_YOUR_KEY is a placeholder. Keep real keys in server-side configuration or a secrets manager; do not embed them in browser code, a public repository, or a support message.
Keys belong to one workspace
A key delegates the creator’s access in its workspace. Effective access is the intersection of the scopes selected for the key and the creator’s current membership permissions. Revoked or expired keys, removed creators, and keys whose creators no longer belong to the workspace cannot authenticate.
Use GET /me to inspect the effective workspace, role, and scopes. The scope name describes the required capability; an operation’s plan checks can still block it.
| Common task | Permission |
|---|---|
| List agents | agents:read |
| Create or edit an agent | agents:write |
| Edit Sales Brain knowledge | knowledge:write |
| Read contacts | contacts:read |
| Import contacts | contacts:write |
| Create or edit a campaign | campaigns:write |
| Preview or confirm launch | campaigns:launch |
| Read analytics | analytics:read |
| Read billing and usage | billing:read |
| Change billing | billing:write |
Do not infer that every scope has a public endpoint. The endpoint reference defines the supported API surface. API keys cannot create or manage other API keys.
Rotate a key
- Create a replacement in Settings → API keys.
- Update your integration and verify it with
GET /me. - Select Revoke beside the old key and confirm Revoke key.
If a key is exposed, revoke it and replace it. Copying a newly created key is the only opportunity to retrieve its full value.