Entornos y claves de API

Cada solicitud a Tokeflow se autentica con una clave de API, y cada clave lleva su propio contexto: a qué entorno apunta, si es seguro exponerla en un navegador y en nombre de qué entidad actúa. Comprender cómo se codifica ese contexto te permite conectar tus integraciones correctamente desde la primera vez.

Esta página cubre la URL base y el versionado, cómo se representan los entornos, las cuatro formas de clave y el ciclo de vida de las claves (crear, rotar, revocar) que administras en el Dashboard de Tokeflow.

URL base y versionado

Todo el tráfico de la API se dirige a un único host, y cada endpoint reside bajo un prefijo de versión.

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

Tokeflow usa versionado por URI. La versión actual es v1, y aparece en la ruta de cada endpoint:

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

No hay un nombre de host separado para pruebas. El entorno en el que operas es una propiedad de la clave que envías, no de la URL. La misma URL base sirve para todos los entornos: Tokeflow resuelve el entorno a partir de la clave en cada solicitud.

Cómo se codifican los entornos

Las claves de Tokeflow son autodescriptivas. Cada clave sigue una anatomía fija, y uno de sus segmentos nombra el entorno al que está vinculada la clave:

{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)

Una clave secreta de Merchant en vivo, por ejemplo, luce así:

sk_live_mer_9f2c4a7b1e8d3c5a6b0f2e1d4c7a9b3e

Leyendo de izquierda a derecha:

Debido a que el entorno está incorporado en la clave:

• Las claves no son portables entre entornos. Una clave emitida para un entorno no se autenticará contra otro.
• Nunca cambias de host ni de versión para cambiar de entorno: cambias de clave.
• Cada entorno mantiene su propio conjunto aislado de claves, datos y configuración. La actividad realizada con la clave de un entorno nunca afecta a la de otro.

Claves secretas frente a públicas

El primer segmento, sk o pk, es lo más importante que debes acertar.

• Las claves secretas (sk_…) autentican llamadas de servidor a servidor. Pueden realizar acciones privilegiadas y nunca deben aparecer en código de navegador, aplicaciones móviles, repositorios públicos, registros ni en ningún lugar donde un tercero pudiera leerlas.
• Las claves públicas (pk_…) están restringidas a un pequeño conjunto de alcances seguros para el cliente y están diseñadas para incrustarse en código de navegador o de cliente. No pueden realizar acciones privilegiadas del servidor.

Las solicitudes del lado del servidor se autentican con el encabezado estándar:

Authorization: Bearer sk_live_mer_xxxxxxxx

Las claves públicas las usa el SDK de cliente de Tokeflow en lugar de pasarse directamente en el encabezado Authorization. Consulta la descripción general del SDK para saber cómo se presentan las claves pk_… en contextos de navegador.

Alcance de Organization frente a Merchant

El tercer segmento, org o mer, determina en nombre de qué entidad actúa la clave. Tokeflow es multiinquilino: una Organization puede contener muchos Merchants.

• Una clave de Merchant se limita automáticamente a su merchant. El merchant se infiere a partir de la clave, por lo que nunca pasas un merchant_id.
• Una clave de Organization abarca todos los merchants de la org. Para los recursos con alcance de merchant, debe identificar explícitamente al merchant destino: mediante el parámetro de consulta merchant_id en solicitudes de listado/obtención, o el campo del cuerpo merchant_id en solicitudes de creación.

# 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"

Más allá del alcance de entidad, cada clave también lleva alcances de permiso en forma resource:action (por ejemplo transactions:read, products:write). Una clave solo puede realizar las acciones que sus alcances permiten. Consulta Autenticación para conocer el modelo de alcances completo.

Las cuatro formas de clave

Combinar el tipo de clave (sk/pk) con el alcance de entidad (org/mer) da cuatro formas de clave distintas. Elige la más restringida que aún cumpla su función.

Ciclo de vida de las claves

Creas, rotas y revocas claves en el Dashboard de Tokeflow durante la incorporación y a lo largo de la vida de tu integración. Las claves se emiten por entorno y por entidad.

Crear una clave

En el Dashboard, crea una clave asignándole:

• Un nombre legible para humanos que identifique la integración (por ejemplo, Prod - Main Backend).
• Un tipo (secreta o pública) y un alcance de entidad (organization o merchant).
• Los alcances de permiso que necesita, en forma resource:action. Concede solo lo que la integración requiera.

Cuando se crea la clave, Tokeflow muestra el valor secreto completo exactamente una vez. Cópialo de inmediato en tu almacén de secretos: no se puede recuperar después. A partir de ese momento, en el Dashboard solo se muestra un prefijo corto y no sensible, para que puedas reconocer la clave sin exponerla.

Usa claves separadas por integración

Emite una clave distinta para cada servicio, entorno e integración. No compartas una misma clave entre varios sistemas.

Almacena los secretos de forma segura

Las claves secretas pertenecen a un gestor de secretos o se inyectan como variables de entorno en el momento del despliegue, nunca codificadas de forma fija en el código fuente, confirmadas en el control de versiones ni incrustadas en paquetes del lado del 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ácticas recomendadas:

• Mantén los secretos en un gestor de secretos dedicado e inyéctalos en tiempo de ejecución.
• Añade los archivos de clave y los archivos .env a .gitignore; escanea los commits en busca de filtraciones accidentales.
• Restringe quién puede leer los secretos de producción.
• Nunca registres los valores completos de las claves. Registra como mucho el prefijo no sensible.

Rota las claves

Rota las claves de forma periódica y siempre que se marchen miembros del equipo con acceso. Tokeflow admite rotación con solapamiento para que puedas renovar claves sin tiempo de inactividad:

1. Crea una nueva clave con el mismo alcance y permisos en el Dashboard.
2. Despliega la nueva clave en tu servicio (mediante tu gestor de secretos).
3. Verifica que la nueva clave está sirviendo tráfico en vivo.
4. Revoca la clave antigua una vez que ya no esté en uso.

Debido a que las claves antigua y nueva son válidas simultáneamente durante el solapamiento, no hay ninguna ventana en la que las solicitudes fallen.

Rotar ante exposición

Si una clave secreta llega a exponerse —confirmada en un repo, filtrada en registros, compartida fuera de tu equipo o enviada a un cliente—, trátala como comprometida:

1. Crea una clave de reemplazo de inmediato.
2. Despliega el reemplazo.
3. Revoca la clave expuesta de inmediato.

Errores que podrías ver

Los problemas de autenticación y autorización devuelven el sobre de error estándar:

{
  "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"
  }
}

Si ves un 401 en una clave que crees válida, comprueba que el segmento de entorno de la clave coincida con el entorno que pretendes llamar.

Próximos pasos

• Autenticación — encabezados, alcances y ejemplos de autenticación resueltos.
• Introducción — cómo encajan la orquestación, el enrutamiento y la gobernanza multiinquilino.
• Descripción general del SDK — usar claves públicas de forma segura en el navegador.