Chaves de API

Toda chamada à API da Koku é autenticada por uma chave de API da sua conta, enviada no cabeçalho Authorization:

Authorization: Bearer koku_live_3f9a1c2b4d5e_<segredo>

A conta e o ambiente vêm da própria chave: nenhum campo do corpo escolhe conta ou ambiente.

#Onde gerar

1. Entre no painel Koku (abre em nova aba) com o seu usuário.
2. Abra Desenvolvedores › Chaves de API e clique em Nova chave.
3. Dê um nome (ex.: "Checkout da loja"), marque só os escopos necessários e, se quiser, uma data de expiração.
4. Confirme com o código do seu aplicativo autenticador (verificação em duas etapas).
5. Copie a chave na hora. Ela aparece uma única vez; a Koku guarda apenas um resumo criptográfico (hash) e não consegue mostrá-la de novo.

Podem gerar chaves o proprietário da conta, o administrador da conta e o desenvolvedor. Uma chave só recebe escopos que o papel de quem a cria pode conceder.

#Formato

koku_<ambiente>_<prefixo>_<segredo>

• ambiente: live (produção). O valor sb fica reservado para as chaves do ambiente de testes, que ainda está em preparação.
• prefixo: 12 caracteres hexadecimais, visíveis no painel para você identificar a chave.
• segredo: a parte secreta. Nunca aparece no painel depois da criação.

Para conferir ambiente e escopos de uma chave sem expor o segredo, use Dados da chave atual:

curl -X GET 'https://api.kokupay.com/v1/api-keys/current' \
  -H "Authorization: Bearer $KOKU_API_KEY"

const response = await fetch('https://api.kokupay.com/v1/api-keys/current', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.KOKU_API_KEY}`,
  },
});

const data = await response.json();
console.log(response.status, data);

import os

import requests

response = requests.request(
    "GET",
    "https://api.kokupay.com/v1/api-keys/current",
    headers={
        "Authorization": f"Bearer {os.environ['KOKU_API_KEY']}",
    },
    timeout=30,
)

print(response.status_code, response.json())

<?php

$ch = curl_init('https://api.kokupay.com/v1/api-keys/current');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KOKU_API_KEY'),
    ],
]);

$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
echo $status, PHP_EOL;
print_r($data);

{
  "id": "a9d4e2f7-0b31-4c6e-8f52-3e7a1d9c6b04",
  "name": "Checkout da loja",
  "prefix": "koku_live_3f9a1c2b4d5e",
  "gateway_id": "5f0c2a9e-1b7d-4c3e-9a51-2d8e6f4b7c10",
  "environment": "production",
  "scopes": [
    "charges:read",
    "charges:write",
    "refunds:write",
    "balance:read",
    "statement:read",
    "payouts:read",
    "webhooks:read",
    "webhooks:write"
  ],
  "expires_at": null,
  "created_at": "2026-10-07T14:00:00.000Z"
}

#Escopos

Escolha só o que a integração usa. Uma chamada sem o escopo necessário responde 403 com details.reason = "missing_scope".

Um checkout típico usa charges:write, charges:read e webhooks:read; se ele também acompanha devoluções, acrescente refunds:write e statement:read. O financeiro usa balance:read, statement:read e payouts:read. Separe chaves por finalidade: se uma vazar, o estrago fica limitado.

#Trocar (rotacionar) uma chave

No painel, em Desenvolvedores › Chaves de API:

• Rotacionar gera uma chave nova com o mesmo nome, escopos e expiração e revoga a antiga na hora.
• Revogar desliga a chave imediatamente. Não dá para desfazer.

Para trocar sem interromper vendas: crie uma chave nova, publique-a na sua integração, confira que as chamadas funcionam e só então revogue a antiga. Troque as chaves periodicamente e sempre que alguém com acesso sair da equipe.

#Nunca no navegador

• Guarde a chave em variável de ambiente ou cofre de segredos (ex.: KOKU_API_KEY).
• Use uma chave por ambiente e por sistema.
• Suspeita de vazamento: revogue no painel e gere outra.