Autenticação

Toda requisição à API Tokeflow é autenticada com uma chave de API. A chave que você apresenta determina duas coisas ao mesmo tempo: quem você é (a Organization ou o Merchant ao qual a chave pertence) e o que você pode fazer (os escopos concedidos a essa chave).

A Tokeflow usa dois tipos de chaves:

• Chaves secretas (sk_…) — acesso completo no lado do servidor. Usadas a partir do seu backend com o cabeçalho Authorization: Bearer.
• Chaves públicas (pk_…) — acesso restrito e seguro para o cliente. Usadas pelo Bridge SDK no navegador para coletar dados de pagamento. Seguras para serem enviadas ao cliente.

O esquema Bearer

Requisições do lado do servidor autenticam-se enviando sua chave secreta no cabeçalho Authorization usando o esquema Bearer:

Authorization: Bearer <secret_key>

curl https://api.tokeflow.com/api/v1/transactions \
  -H "Authorization: Bearer sk_live_mer_4f9a2c7e8b1d6035" \
  -H "Accept: application/json"

Todos os endpoints ficam sob https://api.tokeflow.com/api/v1. Para o modelo completo de requisição/resposta e as convenções, consulte a visão geral da API.

Anatomia da chave

Toda chave codifica seu tipo, ambiente e escopo no prefixo. O formato é:

{sk|pk}_{environment}_{org|mer}_{random}

Exemplo detalhado:

sk_live_mer_4f9a2c7e8b1d6035
│  │    │   └─ random — a porção única e secreta
│  │    └───── scope — org (Organization) ou mer (Merchant)
│  └────────── environment — ex.: live
└───────────── key type — sk (secret) ou pk (public)

Isso significa que você pode reconhecer de relance o que é uma chave:

• pk_live_org_… — chave pública, de Organization
• pk_live_mer_… — chave pública, de Merchant
• sk_live_org_… — chave secreta, de Organization
• sk_live_mer_… — chave secreta, de Merchant

Chaves de Organization vs. chaves de Merchant

A Tokeflow é multi-tenant: uma Organization governa um ou mais Merchants (consulte Organizations e Merchants). Toda chave tem escopo para exatamente uma entidade, e esse escopo altera a forma como os recursos específicos de merchant são endereçados.

Chave de Merchant — o merchant é inferido

Uma chave de Merchant já está vinculada a um merchant, então você nunca passa um merchant_id. O exemplo abaixo lista as transações desse merchant:

curl "https://api.tokeflow.com/api/v1/transactions?limit=20" \
  -H "Authorization: Bearer sk_live_mer_4f9a2c7e8b1d6035" \
  -H "Accept: application/json"

Chave de Organization — identifique o merchant

Uma chave de Organization abrange todo merchant da org, então, para recursos com escopo de merchant, você deve indicar a qual merchant se refere. Em leituras, passe merchant_id como parâmetro de query:

curl "https://api.tokeflow.com/api/v1/transactions?merchant_id=mrc_8a3f12d9&limit=20" \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68" \
  -H "Accept: application/json"

Em escritas, passe merchant_id no body da requisição:

await fetch("https://api.tokeflow.com/api/v1/transactions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TOKEFLOW_ORG_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    merchant_id: "mrc_8a3f12d9",
    amount: 15000, // minor units → R$150.00
    currency: "BRL",
    payment_method: "credit_card",
    // …
  }),
});

Escopos

Permissões são expressas como escopos no formato resource:action. Uma chave recebe uma lista explícita de escopos quando é criada no Tokeflow Dashboard, e uma requisição só é autorizada se a chave carregar o escopo que o endpoint exige.

Escopos comuns:

A divisão :read / :write permite aplicar o menor privilégio: emita chaves somente leitura para cargas de trabalho de relatórios ou analytics, e reserve os escopos de escrita para os serviços que realmente criam ou modificam recursos.

Chaves públicas: o que elas podem fazer

Chaves públicas (pk_…) são projetadas para serem incorporadas em código de navegador. Elas são restritas a um pequeno conjunto de escopos seguros para o cliente — as operações de que o Bridge SDK precisa para coletar dados de pagamento e criar tokens — e não podem ler transações, emitir reembolsos ou tocar em qualquer recurso exclusivo do servidor.

Por causa dessas restrições, chaves públicas são seguras para expor em código do lado do cliente. O Bridge SDK apresenta a chave pública por meio de cabeçalhos específicos do SDK, em vez do cabeçalho Authorization:

X-Public-Key: pk_live_mer_…
X-Session-Id: <uuid>
X-SDK-Version: <semver>

Normalmente você nunca define esses cabeçalhos por conta própria — o SDK os gerencia. Consulte a visão geral do Bridge SDK para detalhes.

Allowlist de IPs (endurecimento opcional)

Para uma camada extra de defesa, você pode restringir uma chave a um conjunto de IPs de origem configurando uma allowlist allowed_ips na chave no Tokeflow Dashboard. Quando definida, requisições de qualquer outro IP são rejeitadas com 403 authorization_error, mesmo que a chave e seus escopos sejam válidos em todo o resto.

A allowlist aceita:

• Endereços IPv4 / IPv6 exatos — 203.0.113.10, 2001:db8::1
• Faixas CIDR — 203.0.113.0/24, 2001:db8::/32
• Curingas para permitir todos os IPs — *, 0.0.0.0/0 ou ::/0

401 vs. 403

A Tokeflow distingue falhas de autenticação de falhas de autorização:

• 401 authentication_error — a Tokeflow não conseguiu estabelecer quem você é. A chave está ausente, malformada, revogada ou expirada.
• 403 authorization_error — a Tokeflow sabe quem você é, mas você não tem permissão para fazer isto. A chave não possui o escopo exigido, ou a requisição veio de um IP fora do allowed_ips da chave.

Uma chave ausente ou inválida retorna 401:

{
  "error": {
    "type": "authentication_error",
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API key",
    "details": {},
    "request_id": "req_8f3c9a1e2d40",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

Uma chave válida que não possui o escopo exigido (ou é bloqueada pela allowlist de IPs) retorna 403:

{
  "error": {
    "type": "authorization_error",
    "code": "INSUFFICIENT_SCOPE",
    "message": "This API key is not permitted to perform this action",
    "details": { "required_scope": "transactions:write" },
    "request_id": "req_3a7d10b9c2e8",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

Próximos passos

• Ambientes e chaves de API — como as chaves são emitidas, rotacionadas e revogadas.
• Visão geral da API — URL base, versionamento, envelopes e convenções.
• Visão geral do Bridge SDK — usando chaves públicas para coletar dados de pagamento no navegador.