Ambientes e chaves de API

Toda requisição à Tokeflow é autenticada com uma chave de API, e cada chave carrega seu próprio contexto: qual ambiente ela tem como alvo, se é seguro expô-la em um navegador e em nome de qual entidade ela atua. Entender como esse contexto é codificado permite que você configure integrações corretamente já na primeira vez.

Esta página cobre a URL base e o versionamento, como os ambientes são representados, as quatro formas de chave e o ciclo de vida das chaves (criar, rotacionar, revogar) que você gerencia no Dashboard da Tokeflow.

URL base e versionamento

Todo o tráfego da API vai para um único host, e cada endpoint fica sob um prefixo de versão.

https://api.tokeflow.com/api/v1

A Tokeflow usa versionamento por URI. A versão atual é v1, e ela aparece no caminho de cada endpoint:

curl https://api.tokeflow.com/api/v1/transactions \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxx"

Não há um hostname separado para testes. O ambiente em que você opera é uma propriedade da chave que você envia, não da URL. A mesma URL base atende todos os ambientes — a Tokeflow resolve o ambiente a partir da chave em cada requisição.

Como os ambientes são codificados

As chaves da Tokeflow são autodescritivas. Cada chave segue uma anatomia fixa, e um de seus segmentos nomeia o ambiente ao qual a chave está vinculada:

{sk|pk}_{environment}_{org|mer}_{random}
   │          │            │         │
   │          │            │         └─ random, high-entropy secret
   │          │            └─ scope: organization (org) or merchant (mer)
   │          └─ environment the key is bound to
   └─ key type: sk = secret (server-side), pk = public (client-safe)

Uma chave secreta de merchant em ambiente live, por exemplo, tem esta aparência:

sk_live_mer_9f2c4a7b1e8d3c5a6b0f2e1d4c7a9b3e

Lendo da esquerda para a direita:

Como o ambiente está embutido na chave:

• As chaves não são portáveis entre ambientes. Uma chave emitida para um ambiente não autenticará em outro.
• Você nunca troca de host ou de versão para mudar de ambiente — você troca de chave.
• Cada ambiente mantém seu próprio conjunto isolado de chaves, dados e configuração. A atividade realizada com a chave de um ambiente nunca toca a de outro.

Chaves secretas vs. públicas

O primeiro segmento, sk ou pk, é a coisa mais importante de se acertar.

• Chaves secretas (sk_…) autenticam chamadas servidor a servidor. Elas podem realizar ações privilegiadas e nunca devem aparecer em código de navegador, aplicativos móveis, repositórios públicos, logs ou em qualquer lugar onde um terceiro pudesse lê-las.
• Chaves públicas (pk_…) são restritas a um pequeno conjunto de escopos seguros para o cliente e foram projetadas para serem embutidas em código de navegador ou de cliente. Elas não podem realizar ações privilegiadas no servidor.

As requisições do lado do servidor autenticam com o cabeçalho padrão:

Authorization: Bearer sk_live_mer_xxxxxxxx

As chaves públicas são usadas pelo SDK cliente da Tokeflow em vez de serem passadas diretamente no cabeçalho Authorization. Veja a visão geral do SDK para saber como as chaves pk_… são apresentadas em contextos de navegador.

Escopo de Organization vs. Merchant

O terceiro segmento, org ou mer, determina em nome de qual entidade a chave atua. A Tokeflow é multi-tenant: uma Organization pode conter muitos Merchants.

• Uma chave de Merchant é automaticamente restrita ao seu merchant. O merchant é inferido a partir da chave, então você nunca passa um merchant_id.
• Uma chave de Organization abrange todos os merchants da org. Para recursos com escopo de merchant, ela deve identificar o merchant alvo explicitamente — via o parâmetro de query merchant_id em requisições de list/get, ou via o campo de body merchant_id em requisições de create.

# Organization key: target a specific merchant with merchant_id
curl "https://api.tokeflow.com/api/v1/transactions?merchant_id=mrc_a1b2c3" \
  -H "Authorization: Bearer sk_live_org_xxxxxxxx"

# Merchant key: merchant is inferred, no merchant_id needed
curl "https://api.tokeflow.com/api/v1/transactions" \
  -H "Authorization: Bearer sk_live_mer_xxxxxxxx"

Além do escopo de entidade, cada chave também carrega escopos de permissão na forma resource:action (por exemplo transactions:read, products:write). Uma chave só pode realizar as ações que seus escopos permitem. Veja Autenticação para o modelo completo de escopos.

As quatro formas de chave

Combinar o tipo de chave (sk/pk) com o escopo de entidade (org/mer) resulta em quatro formas de chave distintas. Escolha a mais restrita que ainda dê conta do trabalho.

Ciclo de vida das chaves

Você cria, rotaciona e revoga chaves no Dashboard da Tokeflow durante o onboarding e ao longo de toda a vida da sua integração. As chaves são emitidas por ambiente e por entidade.

Criar uma chave

No Dashboard, crie uma chave fornecendo a ela:

• Um nome legível por humanos que identifique a integração (por exemplo, Prod - Main Backend).
• Um tipo (secreta ou pública) e um escopo de entidade (organization ou merchant).
• Os escopos de permissão de que ela precisa, na forma resource:action. Conceda apenas o que a integração exigir.

Quando a chave é criada, a Tokeflow exibe o valor secreto completo exatamente uma vez. Copie-o imediatamente para o seu cofre de segredos — ele não pode ser recuperado depois. A partir desse ponto, apenas um prefixo curto e não sensível é exibido no Dashboard, para que você possa reconhecer a chave sem expô-la.

Use chaves separadas por integração

Emita uma chave distinta para cada serviço, ambiente e integração. Não compartilhe uma chave entre vários sistemas.

Armazene segredos com segurança

As chaves secretas pertencem a um gerenciador de segredos ou devem ser injetadas como variáveis de ambiente no momento do deploy — nunca fixadas no código-fonte, commitadas no controle de versão ou embutidas em bundles do lado do cliente.

// Read the key from the environment, never inline it
const apiKey = process.env.TOKEFLOW_SECRET_KEY;

const res = await fetch("https://api.tokeflow.com/api/v1/transactions", {
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
});

Práticas recomendadas:

• Mantenha os segredos em um gerenciador de segredos dedicado e injete-os em tempo de execução.
• Adicione arquivos de chave e arquivos .env ao .gitignore; verifique os commits em busca de vazamentos acidentais.
• Restrinja quem pode ler os segredos de produção.
• Nunca registre em log os valores completos das chaves. Registre no máximo o prefixo não sensível.

Rotacione chaves

Rotacione as chaves em uma programação regular e sempre que membros da equipe com acesso saírem. A Tokeflow suporta rotação com sobreposição, para que você possa trocar chaves sem indisponibilidade:

1. Crie uma nova chave com o mesmo escopo e permissões no Dashboard.
2. Faça o deploy da nova chave para o seu serviço (via seu gerenciador de segredos).
3. Verifique que a nova chave está atendendo ao tráfego real.
4. Revogue a chave antiga assim que ela não estiver mais em uso.

Como as chaves antiga e nova são válidas simultaneamente durante a sobreposição, não há uma janela em que as requisições falhem.

Rotacionar em caso de exposição

Se uma chave secreta for alguma vez exposta — commitada em um repositório, vazada em logs, compartilhada fora da sua equipe ou enviada a um cliente — trate-a como comprometida:

1. Crie uma chave de substituição imediatamente.
2. Faça o deploy da substituta.
3. Revogue a chave exposta imediatamente.

Erros que você pode ver

Problemas de autenticação e autorização retornam o envelope de erro padrão:

{
  "error": {
    "type": "authentication_error",
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid, revoked, or for a different environment.",
    "details": {},
    "request_id": "req_8f3c2a1b9d7e",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

Se você vir um 401 em uma chave que acredita ser válida, verifique se o segmento de ambiente da chave corresponde ao ambiente que você pretende chamar.

Próximos passos

• Autenticação — cabeçalhos, escopos e exemplos práticos de autenticação.
• Introdução — como a orquestração, o roteamento e a governança multi-tenant se encaixam.
• Visão geral do SDK — usando chaves públicas com segurança no navegador.