Autenticação
Crie chaves de API, escolha entre chave secreta e publicável e entenda o que cada acesso permite.
Toda requisição leva uma chave de API no cabeçalho Authorization:
curl https://vamo.ai/api/v1/stores \
-H "Authorization: Bearer sk_live_SUA_CHAVE"A chave define a organização: tudo o que você lê ou altera é da organização em que a chave foi criada.
Criar uma chave
Abra Desenvolvedores → Chaves API e clique em Criar chave API.
Dê um Nome da chave que diga onde ela é usada ("Produção", "Site", "ERP").
Escolha o Tipo de chave e, para uma chave secreta, o Acesso (veja abaixo).
Copie a chave. Ela aparece uma única vez; depois o Vamo mostra só o começo dela (por exemplo sk_live_1a2b3c4d).
Só o proprietário, os administradores e os desenvolvedores da organização criam, veem e revogam chaves. Quando um membro sai da organização, ou perde a permissão de criar chaves, as chaves que ele criou são revogadas.
Tipos de chave
| Tipo | Começa com | Onde usar | O que pode |
|---|---|---|---|
| Secreta | sk_live_ | No seu servidor | Ler, e escrever se tiver acesso Leitura e escrita |
| Publicável | pk_live_ | No navegador ou app | Só ler a loja e os modelos |
Chave publicável
Feita para ficar em código público. Ela só passa em requisições de leitura (GET, HEAD, OPTIONS) a estes endpoints, que não têm dados de clientes:
GET /storeseGET /stores/:idGET /templateseGET /templates/:id
Qualquer outra rota responde 403.
Chave secreta: o acesso
Ao criar uma chave secreta você escolhe o Acesso:
| Acesso | Pode |
|---|---|
| Somente leitura | Listar e consultar (GET). Qualquer POST, PATCH ou DELETE responde 403 |
| Leitura e escrita | Também enviar mensagens e criar ou alterar contatos, conversas, pedidos e webhooks |
Use Somente leitura em relatórios e painéis, e deixe Leitura e escrita para o serviço que realmente envia e altera. Você pode trocar o acesso depois, sem criar outra chave: na lista de chaves, use o interruptor Permitir escrita da linha. A mudança vale já na próxima requisição.
Uma chave publicável é sempre Somente leitura.
Revogar uma chave
Na lista, clique em Revogar na linha da chave. A revogação vale na hora e não tem volta: a próxima requisição com essa chave já responde 401. Para trocar uma chave sem parar a integração, crie a nova, troque no seu sistema e só então revogue a antiga.
Respostas de erro
Os erros de autenticação vêm no formato de sempre: { "error": { "code": "…", "message": "…" } }.
| Status | code | O que fazer |
|---|---|---|
401 | missing_api_key | Envie Authorization: Bearer <chave> (com a palavra Bearer e um espaço) |
401 | invalid_api_key | A chave não existe ou foi copiada pela metade |
401 | api_key_revoked | Crie outra chave |
401 | api_key_expired | Crie outra chave |
403 | publishable_key_read_only | A chave publicável tentou escrever. Use uma chave secreta |
403 | publishable_key_forbidden | A chave publicável só lê lojas e modelos. Use uma chave secreta |
403 | read_only_key | Ligue Permitir escrita ou use outra chave |
Boas práticas
- Guarde a chave secreta numa variável de ambiente ou num cofre de segredos, nunca no repositório.
- Uma chave por sistema: se uma vazar, você revoga só ela.
- A coluna Último uso da lista mostra se uma chave ainda está em uso (ela é atualizada no máximo uma vez por minuto).
- Cada chave tem o seu limite de requisições por minuto. Para separar o tráfego de dois sistemas, dê uma chave a cada um.
- O Vamo guarda um registro de cada requisição à API por 30 dias, sem a chave e sem segredos (o cabeçalho
Authorizatione campos comosecretoutokensão apagados antes de gravar).