Claves de API del Merchant

Estos endpoints impulsan la pantalla de claves de API del Tokeflow Dashboard para un Merchant: enumerar las claves existentes, generar una nueva, consultar qué scopes puede llevar y revocar una clave que ya no deba funcionar. Las claves que gestionan son las mismas credenciales sk_… (secreta) y pk_… (pública) que tu integración presenta a la API pública — el Dashboard es simplemente la forma amigable de gestionarlas.

Las claves secretas otorgan acceso del lado del servidor y pertenecen a un gestor de secretos; las claves públicas son seguras para el cliente y están restringidas a lo 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.

Cómo funciona el flujo de la pantalla de claves

El endpoint de scopes alimenta el formulario de creación de claves: devuelve solo los scopes válidos para este Merchant y el tipo de clave elegido, de modo que el usuario nunca pueda seleccionar un scope que la clave no pudiera llevar. Después de la creación, la clave completa nunca se vuelve a mostrar — la lista identifica cada clave únicamente por su key_prefix.

El objeto de la clave de API

Se devuelve en la creación; el endpoint de listado devuelve el mismo objeto sin el secreto api_key, exclusivo de la creación.

Endpoints

GET/api/v1/merchant/api-keys

Devuelve una lista paginada de las claves de API del Merchant — el Merchant se obtiene del header x-merchant-id.

Parámetros de consulta

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/merchant/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Ejemplo de respuesta — 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"
    },
    {
      "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"
    }
  ],
  "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. La clave completa nunca se incluye aquí; cada clave se identifica por su key_prefix, que no es secreto.

POST/api/v1/merchant/api-keys

Crea una clave de API para el Merchant identificado por x-merchant-id. La respuesta es el único lugar donde se devuelve la clave completa (api_key).

Campos de la solicitud

Ejemplo de solicitud

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

Ejemplo de respuesta — 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/merchant/api-keys/scopes

Devuelve los scopes que se pueden asignar a las claves de API de este Merchant. Se excluyen los scopes exclusivos de la Organization. Filtra por key_type para obtener los scopes válidos para claves públicas o secretas — esto es lo que usa el formulario de creación de claves del Dashboard para completar su selector de scopes antes de llamar a POST /merchant/api-keys.

Parámetros de consulta

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/merchant/api-keys/scopes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --data-urlencode "key_type=secret"

Ejemplo de respuesta — 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": [
    "transactions:*",
    "customers:*"
  ]
}

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 esta entidad y tipo de clave — 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.

DELETE/api/v1/merchant/api-keys/:id

Revoca una clave de API de forma permanente. La revocación surte efecto de inmediato: cualquier solicitud que presente la clave revocada falla la autenticación a partir de ese momento. No hay forma de deshacerlo — si la carga de trabajo aún necesita acceso, crea primero una clave de reemplazo.

Parámetros de ruta

Ejemplo de solicitud

curl -X DELETE https://api.tokeflow.com/api/v1/merchant/api-keys/ak_9f2e6c81 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Ejemplo de respuesta — 204 No Content

El cuerpo de la respuesta está vacío.

Errores

Los casos más comunes para estos endpoints:

Consulta Errores para conocer el formato general de error usado en toda la API.

Relacionado

• Claves de API (API pública) — gestiona claves mediante programación desde tu backend, incluyendo pausar/reactivar.
• 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.
• Errores — el envoltorio estándar de errores.