Autenticação

Aprenda a estruturar as suas requisições autenticadas aos servidores do Cord.

Bearer Tokens

A API do Cord usa tokens do portador (Bearer Tokens) para autenticar as requisições recebidas. Você deve enviar a chave de API que gerou no painel como um header HTTP Authorization.

Todas as requisições devem ser feitas por HTTPS. As requisições sem autenticação ou enviadas por HTTP simples falham.

Exemplo de requisição:

curl -X GET "https://cordhq.app/api/v1/cotizaciones" \
     -H "Authorization: Bearer sk_live_tU..."

Chaves secretas e publicáveis

O Cord tem três tipos de chave:

Secretas (sk_): somente nos seus servidores. Somente leitura ou leitura e escrita sobre toda a API.
Restritas (rk_): somente nos seus servidores, com permissão por recurso (none, read ou write). Use-as para dar a uma integração de terceiros exatamente o que ela precisa. Veja chaves restritas.
Publicáveis (pk_): para o navegador, com uma lista fixa de rotas.

Mascaramento automático de dados

As chaves publicáveis têm restrições de segurança automáticas impostas pela API. Por exemplo, se você consultar a API de Produtos usando uma chave publicável, o servidor do Cord omite automaticamente o campo costo (margem) para garantir que os visitantes do seu site não descubram as suas margens de lucro.

Além disso, uma Publishable Key só pode ser usada em quatro rotas: GET /api/v1/productos, POST /api/v1/cotizaciones, GET /api/v1/elements/config e POST /api/v1/elements/ai-draft. Qualquer outra responde 403 insufficient_scope. A requisição também deve enviar um header Origin ou Referer que corresponda aos domínios permitidos da sua organização, configurados em Configurações › Gerador de orçamentos incorporável. Uma pk_live_ sem domínios configurados responde 403 origin_allowlist_required; uma pk_test_ é aceita de qualquer origem.

Atenção: Nunca exponha as suas chaves secretas. Se a sua chave secreta for comprometida, revogue-a imediatamente na aba Chaves do Cord Workbench.

Chaves restritas

Uma chave rk_ tem um nível por recurso. O Cord deriva o recurso da rota, então uma rota nova da API já nasce proibida para as chaves restritas existentes até que você dê permissão a ela.

Recurso	Rotas
`cotizaciones`	`/api/v1/cotizaciones/*`
`clientes`	`/api/v1/clientes/*`
`productos`	`/api/v1/productos/*`
`facturas`	`/api/v1/facturas/*`
`cobranza`	`/api/v1/cobranza`
`tareas`	`/api/v1/tareas`
`eventos`	`/api/v1/events`
`webhooks`	`/api/v1/webhooks/*`
`elements`	`/api/v1/elements/*`
`test_helpers`	`/api/v1/test_helpers/*`
`setup`	`/api/v1/setup/*`

read permite GET; write permite também criar, editar e executar as ações. GET /api/v1/me responde a qualquer chave secreta ou restrita. No servidor MCP, uma chave restrita aplica o mesmo nível por recurso a cada ferramenta (veja permissões por ferramenta). Sem permissão, a resposta é 403 insufficient_permissions e nomeia o recurso.

IPs permitidos

Você pode fixar até 20 IPs ou faixas CIDR (IPv4 ou IPv6) em uma chave sk_ ou rk_. O Cord compara o IP de origem registrado pela sua rede de entrega, não um header que o cliente possa escrever, então X-Forwarded-For não serve para contornar a lista. Uma requisição a partir de outro IP responde 403 ip_not_allowed e fica no log de auditoria da sua organização, uma vez por hora por IP.

As Publishable Keys são limitadas por domínio em Configurações › Gerador de orçamentos incorporável, não por IP.

Expiração e rotação

Ao criar uma chave, você pode escolher que ela expire em 7, 30, 90 ou 365 dias; depois disso, ela responde 401 key_expired. Rotacionar cria uma chave nova com as mesmas permissões, os mesmos IPs e a mesma versão da API, e mantém a anterior ativa pelo tempo que você escolher (imediatamente, 1 hora, 24 horas ou 7 dias) enquanto você atualiza os seus sistemas. A chave em período de carência deixa de contar no limite do seu plano. Criar, editar, rotacionar e revogar chaves fica registrado no log de auditoria com quem fez e a partir de qual IP.

Chaves incluídas por plano

Cada plano inclui um número máximo de chaves ativas: 2 no Grátis, 5 no Starter, 20 no Profissional, 50 no Scale e 200 no Developer. Contam as chaves secretas, restritas e publicáveis que não estão revogadas, expiradas nem em período de carência por uma rotação; as conexões autorizadas por OAuth (Zapier, Make) não contam. Ao atingir o limite, o Workbench não deixa você criar outra até revogar uma.

Se a sua organização ficar com mais chaves ativas do que o plano inclui (por exemplo, depois de mudar para um plano inferior), as mais antigas continuam funcionando e as que excedem a cota respondem 402 subscription_key_limit até você revogar chaves ou mudar para um plano superior.

Verificação rápida de identidade

Se você precisar testar se a sua chave de API está funcionando corretamente e a qual conta ela pertence, pode usar o endpoint me:

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