Autenticación

Cada solicitud a la API de Tokeflow se autentica con una clave de API. La clave que presentas determina dos cosas a la vez: quién eres (la Organization o el Merchant al que pertenece la clave) y qué puedes hacer (los scopes concedidos a esa clave).

Tokeflow utiliza dos tipos de claves:

• Claves secretas (sk_…) — acceso completo del lado del servidor. Se usan desde tu backend con el encabezado Authorization: Bearer.
• Claves públicas (pk_…) — acceso restringido y seguro para el cliente. Las usa el Bridge SDK en el navegador para recopilar los datos de pago. Es seguro enviarlas al cliente.

El esquema Bearer

Las solicitudes del lado del servidor se autentican enviando tu clave secreta en el encabezado Authorization mediante el 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 los endpoints residen bajo https://api.tokeflow.com/api/v1. Para conocer el modelo completo de solicitud/respuesta y las convenciones, consulta la descripción general de la API.

Anatomía de una clave

Cada clave codifica su tipo, entorno y alcance en el prefijo. El formato es:

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

Ejemplo desglosado:

sk_live_mer_4f9a2c7e8b1d6035
│  │    │   └─ random — the unique, secret portion
│  │    └───── scope — org (Organization) or mer (Merchant)
│  └────────── environment — e.g. live
└───────────── key type — sk (secret) or pk (public)

Esto significa que puedes reconocer de un vistazo qué es una clave:

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

Claves de Organization frente a claves de Merchant

Tokeflow es multiinquilino: una Organization gobierna uno o más Merchants (consulta Organizations y Merchants). Cada clave tiene alcance sobre exactamente una entidad, y ese alcance cambia la forma en que se direccionan los recursos específicos de cada merchant.

Clave de Merchant — el merchant se infiere

Una clave de Merchant ya está vinculada a un único merchant, por lo que nunca pasas un merchant_id. El siguiente ejemplo lista las transacciones de ese merchant:

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

Clave de Organization — identifica el merchant

Una clave de Organization abarca todos los merchants de la organización, por lo que para los recursos con alcance de merchant debes indicar a qué merchant te refieres. En las lecturas, pasa merchant_id como parámetro de consulta:

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"

En las escrituras, pasa merchant_id en el cuerpo de la solicitud:

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",
    // …
  }),
});

Scopes

Los permisos se expresan como scopes con el formato resource:action. A una clave se le concede una lista explícita de scopes cuando se crea en el Dashboard de Tokeflow, y una solicitud se autoriza únicamente si la clave lleva el scope que exige el endpoint.

Scopes comunes:

La división :read / :write te permite aplicar el mínimo privilegio: emite claves de solo lectura para cargas de trabajo de informes o analíticas, y reserva los scopes de escritura para los servicios que realmente crean o modifican recursos.

Claves públicas: qué pueden hacer

Las claves públicas (pk_…) están diseñadas para incrustarse en el código del navegador. Están restringidas a un pequeño conjunto de scopes seguros para el cliente — las operaciones que el Bridge SDK necesita para recopilar datos de pago y crear tokens — y no pueden leer transacciones, emitir reembolsos ni acceder a ningún recurso exclusivo del servidor.

Debido a esas restricciones, las claves públicas se pueden exponer de forma segura en código del lado del cliente. El Bridge SDK presenta la clave pública mediante encabezados específicos del SDK en lugar del encabezado Authorization:

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

Normalmente nunca configuras estos encabezados tú mismo — el SDK los gestiona. Consulta la descripción general del Bridge SDK para más detalles.

Listas de IP permitidas (endurecimiento opcional)

Para una capa adicional de defensa, puedes restringir una clave a un conjunto de IPs de origen configurando una lista de permitidos allowed_ips en la clave dentro del Dashboard de Tokeflow. Cuando se establece, las solicitudes desde cualquier otra IP se rechazan con 403 authorization_error, incluso si la clave y sus scopes son por lo demás válidos.

La lista de permitidos acepta:

• Direcciones IPv4 / IPv6 exactas — 203.0.113.10, 2001:db8::1
• Rangos CIDR — 203.0.113.0/24, 2001:db8::/32
• Comodines para permitir todas las IPs — *, 0.0.0.0/0 o ::/0

401 frente a 403

Tokeflow distingue los fallos de autenticación de los fallos de autorización:

• 401 authentication_error — Tokeflow no pudo establecer quién eres. La clave falta, está mal formada, ha sido revocada o ha expirado.
• 403 authorization_error — Tokeflow sabe quién eres, pero no tienes permiso para hacer esto. A la clave le falta el scope requerido, o la solicitud provino de una IP fuera de los allowed_ips de la clave.

Una clave faltante o inválida devuelve 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"
  }
}

Una clave válida a la que le falta el scope requerido (o que está bloqueada por la lista de IP permitidas) devuelve 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 pasos

• Entornos y claves de API — cómo se emiten, rotan y revocan las claves.
• Descripción general de la API — URL base, versionado, envolturas y convenciones.
• Descripción general del Bridge SDK — uso de claves públicas para recopilar datos de pago en el navegador.