Pasarela
Entrar

Seguridad

Claves de API

Cómo crear, rotar y revocar claves sin cortar el servicio, y cómo manejar el secreto de webhooks.

Hay dos secretos por empresa: la clave de API, con la que tu servidor llama a la pasarela, y el secreto de webhooks, con el que compruebas que un aviso viene de la pasarela. Son independientes y se rotan por separado.

Clave de APISecreto de webhooks
FormatoClave de APIsk_test_ o sk_live_ + 48 caracteres hexadecimalesSecreto de webhookswhsec_ + 48 caracteres hexadecimales
Cuántos a la vezClave de APIVarias activasSecreto de webhooksUno
Se puede volver a verClave de APINo. Solo al crearla; el servidor guarda su huella SHA-256.Secreto de webhooksSí, con GET /v1/webhook/secret
RotaciónClave de APICrear otra, cambiar, revocar la viejaSecreto de webhooksInmediata: el anterior deja de valer

Varias claves activas#

Una empresa puede tener varias claves a la vez, cada una con un nombre (label). Sirve para dar una clave distinta a cada servicio y para rotar sin corte. Listar claves de API muestra de cada una su prefijo (los primeros 12 caracteres), cuándo se creó, cuándo se usó por última vez y si está revocada.

Rotar sin corte#

  1. 1

    Crea la clave nueva

    Con Crear clave de API. Guarda api_key en ese momento: no se vuelve a mostrar.

  2. 2

    Despliega la clave nueva

    Cámbiala en tus servidores. Mientras tanto, la vieja sigue funcionando.

  3. 3

    Comprueba que la vieja ya no se usa

    Mira last_used_at de la clave vieja en Listar claves de API: debe dejar de avanzar.

  4. 4

    Revoca la vieja

    Con Revocar clave de API. Deja de funcionar de inmediato y no se puede reactivar.

1curl -X POST https://api.pasarela.hi-g.io/v1/api-keys \2  -H "x-api-key: sk_test_4f9c…" \3  -H "content-type: application/json" \4  -d '{"label": "Rotación octubre"}'
  • No se puede revocar la única clave activa: la API responde 409 con Es la única clave activa: crea otra antes de revocar esta.
  • Si una clave se filtró, crea otra y revoca la filtrada enseguida, aunque eso corte algún servicio que aún la use.
  • Si perdiste todas tus claves, la plataforma puede crearte una nueva.

Dónde guardarlas#

  • En variables de entorno o en un gestor de secretos del servidor. Nunca en el código ni en el repositorio.
  • Nunca en una app móvil ni en JavaScript del navegador: cualquiera podría extraerlas.
  • No las escribas en logs. Para identificar una clave usa su prefijo (sk_test_4f9c).
  • Una clave distinta por entorno y por servicio, con un label que diga dónde vive.

Secreto de webhooks#

Se entrega al crear la empresa y se consulta con Ver secreto de webhooks. Rotar secreto de webhooks genera uno nuevo y lo devuelve.

La rotación del secreto es inmediata

No hay un período en el que valgan los dos. Desde la rotación, todos los avisos (también los reintentos de eventos anteriores) van firmados con el secreto nuevo. Los avisos que tu servidor rechace mientras carga el secreto nuevo se reintentan solos (el primero a los 10 segundos), así que no se pierde ninguno; para no depender de eso, sigue estos pasos.

  1. 1

    Prepara tu servidor para dos secretos

    Haz que la verificación acepte una lista de secretos y dé por buena la firma si coincide con cualquiera.

  2. 2

    Rota y carga el nuevo

    Llama a la rotación y añade el secreto devuelto a la lista de tu servidor.

  3. 3

    Quita el viejo

    Cuando el nuevo esté desplegado, elimina el anterior de la lista.