Claves de API

Cada solicitud a la API de Tokeflow se autentica con una clave de API — una credencial vinculada exactamente a una entidad (una Organization o uno de sus Merchants) y a una lista explícita de scopes. Los endpoints de esta página gestionan esas claves mediante programación: crea una clave con scopes de privilegio mínimo, lista las existentes, pausa una clave temporalmente y revócala definitivamente. Todo lo que el Dashboard de Tokeflow hace con las claves, tu backend puede automatizarlo — útil para flujos de incorporación que generan una clave por Merchant, y para la rotación programada de credenciales.

Las claves vienen en dos tipos. Las claves secretas (sk_…) otorgan acceso del lado del servidor y se envían en el encabezado Authorization: Bearer; las claves públicas (pk_…) son seguras para el cliente y están restringidas a los scopes que el Bridge SDK necesita en el navegador. Consulta Autenticación para conocer el modelo completo, y Entornos y claves de API para saber cómo las claves codifican el entorno y la entidad en su prefijo.

Ciclo de vida y rotación de claves

Al rotar, crea y despliega siempre la clave de reemplazo antes de revocar la anterior — la revocación surte efecto de inmediato, y cualquier servicio que aún tenga la clave antigua comenzará a recibir 401 authentication_error.

El objeto de la clave de API

Todos los endpoints de esta página lo devuelven. La respuesta de creación además incluye api_key — el secreto completo — una única vez.

Endpoints

GET/api/v1/api-keys

Devuelve una lista paginada de claves de API. Las Organizations pueden filtrar por entity_type y entity_id para ver las claves de un Merchant específico.

Parámetros de consulta

Solicitud de ejemplo

curl -G https://api.tokeflow.com/api/v1/api-keys \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68" \
  --data-urlencode "entity_type=merchant" \
  --data-urlencode "entity_id=mrc_8a3f12d9" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Respuesta de ejemplo — 200 OK

{
  "data": [
    {
      "id": "ak_9f2e6c81",
      "entity_type": "merchant",
      "entity_id": "mrc_8a3f12d9",
      "name": "Checkout service (production)",
      "key_prefix": "sk_live_mer_7d21",
      "scopes": ["transactions:read", "transactions:write"],
      "allowed_ips": ["203.0.113.10", "198.51.100.0/24"],
      "is_active": true,
      "expires_at": null,
      "last_used_at": "2026-08-11T18:22:04.000Z",
      "created_at": "2026-03-02T09:15:00.000Z",
      "key_hash": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3"
    },
    {
      "id": "ak_5b0d3a47",
      "entity_type": "merchant",
      "entity_id": "mrc_8a3f12d9",
      "name": "Storefront widget",
      "key_prefix": "pk_live_mer_0c1d",
      "scopes": ["tokens:read"],
      "allowed_ips": null,
      "is_active": false,
      "expires_at": "2026-12-31T23:59:59.000Z",
      "last_used_at": "2026-07-30T10:41:52.000Z",
      "created_at": "2026-01-20T16:00:00.000Z",
      "key_hash": "3c363836cf4e16666669a25da280a1865c2d2874"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

data contiene las claves de la página actual y meta los metadatos de paginación — avanza page mientras has_next sea true. Consulta Paginación y filtrado para conocer el patrón general.

POST/api/v1/api-keys

Crea una clave de API para una Organization o un Merchant. La respuesta es el único lugar donde se devuelve la clave completa (api_key).

Campos de la solicitud

Códigos de respuesta

Solicitud de ejemplo

curl -X POST https://api.tokeflow.com/api/v1/api-keys \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "merchant",
    "entity_id": "mrc_8a3f12d9",
    "name": "Checkout service (production)",
    "scopes": ["transactions:read", "transactions:write"],
    "allowed_ips": ["203.0.113.10", "198.51.100.0/24"],
    "key_type": "secret"
  }'

Respuesta de ejemplo — 201 Created

{
  "id": "ak_9f2e6c81",
  "entity_type": "merchant",
  "entity_id": "mrc_8a3f12d9",
  "name": "Checkout service (production)",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": ["transactions:read", "transactions:write"],
  "allowed_ips": ["203.0.113.10", "198.51.100.0/24"],
  "is_active": true,
  "expires_at": null,
  "last_used_at": null,
  "created_at": "2026-08-12T14:03:00.000Z",
  "api_key": "sk_live_mer_7d21c39ab8e4f560",
  "key_hash": "6dcd4ce23d88e2ee9568ba546c007c63d9131c1b"
}

GET/api/v1/api-keys/scopes

Devuelve todos los scopes válidos que se pueden asignar a las claves de API. Filtra por entity_type (organization/merchant) y/o key_type (secret/public) para acotar los resultados a lo que una clave dada realmente podría llevar — útil para validar una lista de scopes antes de llamar a POST /api-keys, o para construir un formulario de creación de claves.

Parámetros de consulta

Solicitud de ejemplo

curl -G https://api.tokeflow.com/api/v1/api-keys/scopes \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68" \
  --data-urlencode "entity_type=organization" \
  --data-urlencode "key_type=secret"

Respuesta de ejemplo — 200 OK (truncado)

{
  "scopes": [
    {
      "scope": "transactions:read",
      "description": "List and view transactions"
    },
    {
      "scope": "transactions:write",
      "description": "Create, capture, and refund transactions"
    },
    {
      "scope": "customers:read",
      "description": "List and view customers"
    }
  ],
  "wildcards": [
    "org:*",
    "org:transactions:*"
  ]
}

Cada elemento de scopes empareja la cadena del scope con una descripción legible. wildcards enumera las cadenas de scopes comodín válidas para la entidad/tipo de clave solicitados — un comodín otorga todos los scopes que cubre, así que resérvalos para servicios de confianza y estrictamente controlados, y prefiere listas explícitas de scopes en todos los demás casos.

PATCH/api/v1/api-keys/:id

Actualiza el estado de activación de una clave. Establece is_active en false para desactivar la clave — las solicitudes que la usen empezarán a fallar de inmediato con 401 authentication_error — o vuelve a true para reactivarla. Úsalo como el interruptor reversible; usa revocar cuando la clave no deba volver nunca.

Campos de la solicitud

Solicitud de ejemplo

curl -X PATCH https://api.tokeflow.com/api/v1/api-keys/ak_9f2e6c81 \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Respuesta de ejemplo — 200 OK

{
  "id": "ak_9f2e6c81",
  "entity_type": "merchant",
  "entity_id": "mrc_8a3f12d9",
  "name": "Checkout service (production)",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": ["transactions:read", "transactions:write"],
  "allowed_ips": ["203.0.113.10", "198.51.100.0/24"],
  "is_active": false,
  "expires_at": null,
  "last_used_at": "2026-08-11T18:22:04.000Z",
  "created_at": "2026-08-12T14:03:00.000Z",
  "key_hash": "6dcd4ce23d88e2ee9568ba546c007c63d9131c1b"
}

Se devuelve un 403 si la clave existe pero no pertenece a tu entidad, y un 404 si no existe.

POST/api/v1/api-keys/:id/revoke

Revoca una clave de API, desactivándola de forma permanente. La revocación surte efecto de inmediato: toda solicitud que presente la clave revocada falla con 401 authentication_error. A diferencia de una desactivación mediante PATCH, una clave revocada queda retirada definitivamente — si la carga de trabajo aún necesita acceso, crea primero una clave de reemplazo.

Solicitud de ejemplo

curl -X POST https://api.tokeflow.com/api/v1/api-keys/ak_9f2e6c81/revoke \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68"

Respuesta de ejemplo — 200 OK

{
  "id": "ak_9f2e6c81",
  "entity_type": "merchant",
  "entity_id": "mrc_8a3f12d9",
  "name": "Checkout service (production)",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": ["transactions:read", "transactions:write"],
  "allowed_ips": ["203.0.113.10", "198.51.100.0/24"],
  "is_active": false,
  "expires_at": null,
  "last_used_at": "2026-08-11T18:22:04.000Z",
  "created_at": "2026-08-12T14:03:00.000Z",
  "key_hash": "6dcd4ce23d88e2ee9568ba546c007c63d9131c1b"
}

Se devuelve un 403 si la clave no pertenece a tu entidad, y un 404 si no existe.

Errores

Los errores usan el envoltorio estándar. Los casos más comunes para este recurso:

Consulta Errores para ver el envoltorio completo y el catálogo de tipos.

Relacionado

• Autenticación — el esquema Bearer, los scopes y la anatomía de las claves.
• Entornos y claves de API — ciclo de vida de las claves, almacenamiento y prácticas de rotación.
• Paginación y filtrado — convenciones de listado usadas por el endpoint de listado.
• Errores — el envoltorio estándar de errores.