KEPLIN Docs

APIs & GraphQL Claves de API

Claves de API

Generar, delimitar y revocar claves API — el acceso de los sistemas externos al GraphQL de tus apps.

Los sistemas externos — un ERP que sincroniza clientes, un sitio que crea pedidos, una integración de facturación — llaman al GraphQL de las apps con una clave API: un secreto enviado en el header x-api-key de cada petición. Las claves se gestionan a nivel de la plataforma y se comparten entre apps: cada clave tiene un scope — eliges las apps y, por app, todos los endpoints o solo algunos. Una integración de facturación puede, por ejemplo, leer cuentas en la app Gestión de Clientes y escribir documentos en otra app, con una única clave.

Nota

Las claves son de quien administra la plataforma: la página Claves API solo está disponible para cuentas de administrador.

La página Claves API

Abre el menú Claves API en la navegación global. La lista muestra todas las claves de la plataforma:

Columna Qué es
Nombre El nombre que le diste a la clave — identifica la integración.
Prefijo Los primeros caracteres de la clave (ej. amk_A1b2C3…) — sirven para reconocer cuál es cuál sin mostrar nunca la clave entera.
Scope Las apps a las que da acceso y, por app, «todos los endpoints» o la lista de los concedidos.
Estado activa o revocada.
Último uso Cuándo se usó la clave por última vez — nunca, si aún no se usó.

La página Claves API, con el scope y el último uso de cada clave.
La página Claves API, con el scope y el último uso de cada clave.

Consejo

La columna Último uso es tu herramienta de limpieza: una clave con meses sin uso es candidata a revocación.

Crear una clave API

  1. Pulsa Nueva clave API.
  2. Dale un Nombre de la clave — ej. integracion-facturacion.
  3. En Scope — apps y endpoints permitidos, marca las apps a incluir. Por defecto, cada app marcada concede «Todos los endpoints de esta app.»
  4. Para apretar el acceso en una app, marca Restringir a endpoints específicos y elige las APIs una a una. En una API de Tabla, la concesión cubre todas las operaciones activas — la lista muestra «da acceso a: getContas, addContas, …» para que sepas exactamente qué concedes.
  5. Pulsa Generar clave API.

El modal de creación de una clave API, con el scope por app y endpoint.
El modal de creación de una clave API, con el scope por app y endpoint.

Copiar y guardar la clave

Después de generar, la ventana muestra la Clave en texto claro — una única vez. Cópiala con Copiar y guárdala en un sitio seguro (un gestor de secretos, la caja fuerte de tu equipo). Cuando cierres la ventana ya no la vuelves a ver — la plataforma no guarda la clave en claro; si la pierdes, solo podrás revocarla y generar otra.

La clave generada, en texto claro por única vez, con el botón Copiar.
La clave generada, en texto claro por única vez, con el botón Copiar.

Atención

Trata la clave como una contraseña: no la metas en código fuente, ni en URLs, ni en pantallas de usuario. Si sospechas de una fuga, revoca ya — generar una clave nueva cuesta segundos.

Usar la clave

La clave va en el header x-api-key de cada petición al endpoint GraphQL de la app:

curl -X POST 'https://tu-host/api/graphql/gestao-clientes' \
  -H 'content-type: application/json' \
  -H 'x-api-key: amk_………' \
  -d '{"query":"query { getContas(take: 5) { id nome } }"}'

La pestaña Docs de cada API genera este ejemplo (y la variante JavaScript) ya con la operación correcta — solo falta tu clave.

Lo que una clave ve y no ve:

  • Solo APIs publicadas — borradores nunca, incluso con scope de app entera.
  • Solo lo que el scope concede: llamar a una app fuera del scope devuelve 403 — API key not authorised for this project; llamar a un endpoint fuera del scope, 403 — API key not authorised for this endpoint.
  • Siempre la versión principal de la app (o la versión publicada de la dirección usada) — nunca la versión de trabajo de un developer.

Límites y errores

Cada clave tiene un techo de peticiones por minuto. Las respuestas de error que una integración debe saber tratar:

Respuesta Significado Qué hacer
401 Clave ausente, inválida, expirada o revocada. Verifica el header y el estado de la clave en la lista.
403 Clave válida pero sin acceso a la app o al endpoint. Ajusta el scope — genera una clave nueva con el scope correcto.
429 Techo de peticiones por minuto alcanzado. Espera el tiempo indicado en el header retry-after y repite.

Revocar una clave

  1. En la lista, pulsa el icono de revocar de la fila.
  2. Confirma en Revocar clave.

La revocación es inmediata: todas las apps consumidoras de esta clave pierden el acceso en la petición siguiente. Una clave revocada no puede reactivarse — queda en la lista, marcada revocada, como registro.

¿Por qué no…?

  • Perdí la clave — ¿puedo verla otra vez? No. La clave en claro solo se muestra en el momento de la creación. Revoca la antigua y genera otra.
  • Necesito dar acceso a un endpoint más — ¿edito la clave? El scope se define en la creación. Genera una clave nueva con el scope completo, cámbiala en la integración y revoca la antigua.
  • ¿Por qué recibe la integración 403 en un endpoint nuevo? La clave fue restringida a endpoints específicos y el nuevo no está en la lista — el mismo remedio: clave nueva con el scope correcto.
  • ¿La clave da acceso a las pantallas de la app? No. Una clave solo habla con el endpoint GraphQL. Las cuentas de usuarios de la app son otra cosa, gestionadas en los ajustes de la propia app.