Authentication

Gerencie suas API Keys para acessar a API de forma segura e controlada.

Como Funciona

A API Vendor utiliza API Keys para autenticação. Cada chave é vinculada a um usuário e possui configurações individuais de rate limit, escopos e expiração.

Para autenticar, inclua sua API Key no header X-Api-Key em todas as requisições.

Header de autenticação

X-Api-Key: vk_sua_api_key_aqui

Segurança

Nunca exponha sua API Key em código frontend, repositórios públicos ou logs. Trate-a como uma senha.

Criar API Key

POST

/api/api-keys

Cria uma nova API Key para o usuário autenticado

Parameter	Type	Required	Description
`name`	string	Required	Nome identificador (ex: "Produção", "Integração CRM")
`scopes`	string[]	Optional	Escopos permitidos. Omitir = acesso total.
`rateLimit`	number	Optional	Limite de requisições por minuto (padrão: 60)
`expiresInDays`	number	Optional	Dias até expirar. Omitir = sem expiração.

Request

curl -X POST https://api.vendoria.com.br/api/api-keys \
  -H "X-Api-Key: vk_chave_existente" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integração CRM",
    "rateLimit": 120,
    "expiresInDays": 365
  }'

Response — a chave completa aparece apenas uma vez

{
  "id": "clxyz...",
  "name": "Integração CRM",
  "key": "vk_a1b2c3d4e5f6...",
  "prefix": "vk_a1b2c3d4",
  "scopes": null,
  "rateLimit": 120,
  "expiresAt": "2027-03-06T00:00:00Z",
  "createdAt": "2026-03-06T00:00:00Z"
}

Importante

A chave completa (key) é retornada apenas na criação. Após isso, apenas o prefixo será visível.

Listar API Keys

GET

/api/api-keys

Lista todas as API Keys do usuário (sem a chave completa)

Response

[
  {
    "id": "clxyz...",
    "name": "Integração CRM",
    "prefix": "vk_a1b2c3d4",
    "scopes": null,
    "rateLimit": 120,
    "lastUsedAt": "2026-03-06T12:00:00Z",
    "expiresAt": "2027-03-06T00:00:00Z",
    "isActive": true,
    "createdAt": "2026-03-06T00:00:00Z"
  }
]

Revogar API Key

DELETE

/api/api-keys/:id

Revoga (desativa) uma API Key permanentemente

Request

curl -X DELETE https://api.vendoria.com.br/api/api-keys/clxyz... \
  -H "X-Api-Key: vk_sua_api_key"

Escopos Disponíveis

Se scopes for null, a chave tem acesso total. Caso contrário, restrinja a um array de escopos:

Scope	Recursos
`agents`	Agentes de voz
`dids`	Números de telefone (DIDs)
`conversations`	Conversas e mensagens
`calls`	Chamadas outbound
`tools`	Ferramentas e integrações
`tts`	Text-to-Speech
`wavoip`	Integração Wavoip/WhatsApp