Autenticação e chaves de API (API Keys)

Suas chaves de API são a porta de entrada da sua conta. Trate-as com o mesmo cuidado que a senha do seu banco de dados.

Onde são geradas

Ative o Modo desenvolvedor (Sua conta › Preferências) e abra a aba Chaves do Workbench de Desenvolvedores, a pílula que aparece no canto inferior da tela (/app?wb=api). Ali você cria chaves novas, escolhe o escopo delas (leitura ou escrita) e as revoga. A chave secreta é mostrada uma única vez ao ser criada; guarde-a em um gerenciador de segredos, nunca no código-fonte.

Autenticação

A API é REST sobre HTTPS. Cada solicitação leva sua chave no header Authorization:

curl https://cordhq.app/api/v1/me \
  -H "Authorization: Bearer sk_live_your_key"

Resposta:

{ "org": { "id": "...", "nombre": "Your Business", "plan": "pro" }, "scope": "write", "mode": "live" }

Ambientes (Live vs Test)

Ao criar uma chave, você escolhe o modo dela:

• Test (sk_test_...): não consome seu medidor de uso da API nem conta para o seu faturamento. Opera sobre o ambiente de teste da sua conta (uma organização espelho, isolada dos seus dados reais — o mesmo mecanismo do interruptor “Ambiente de teste” do seletor de organização). A primeira chamada com uma chave de teste cria essa organização espelho, se ela ainda não existir. Se a timbragem do CFDI é real ou simulada depende de você ter o seu CSD conectado, não do modo da chave. Veja Testar o Cord sem afetar sua produção.
• Live (sk_live_...): use-a em produção. Cada chamada conta para o consumo do seu plano.

Escopos (Scopes)

• Leitura (read): consulta orçamentos, clientes, produtos e recebíveis.
• Escrita (write): além disso, pode criar orçamentos, clientes e produtos.

Conexões autorizadas

O Zapier e o Make não usam chaves: eles se conectam com um clique em uma tela do Cord. Cada conexão aparece na mesma lista como Conexão autorizada, com o nome do app, e não conta para o número de chaves do seu plano. Para cortar o acesso de um app, revogue a conexão dele da mesma forma que uma chave; o app pedirá que você o autorize novamente.

Rotação de chaves

Se uma chave vazou (p. ex., foi enviada por engano ao GitHub), ou simplesmente chegou a hora de trocá-la:

1. Abra a aba Chaves do Workbench (ative-o em Sua conta › Preferências se não o estiver vendo).
2. Clique em Rotacionar na chave. O Cord gera uma chave nova e permite escolher por quanto tempo a anterior continua funcionando: nenhum, 1 hora, 24 horas ou 7 dias, para que você atualize seus servidores sem cortar o tráfego.
3. Se a chave ficou exposta, rotacione sem período de carência ou revogue-a: a revogação é imediata e qualquer solicitação com essa chave responderá 401.