Gestión de API Keys

No es una superficie de la API pública

Crear, listar, revocar o eliminar API keys no son rutas de api.fenicia.io. Esas operaciones viven exclusivamente en el host de autenticación (account.fenicia.io, en singular) y hoy solo las consume el panel de Fenicia — no son un endpoint público soportado para invocar directamente desde tu integración. El camino soportado es generar y administrar tus llaves desde la interfaz web.

Generar una API key

1

Inicia sesión en tu panel de Fenicia

Abre app.fenicia.io e ingresa con tu correo y contraseña.

2

Abre Configuración → Claves API

En la barra lateral izquierda haz clic en Configuración y luego en Claves API. Verás la lista de llaves existentes o un estado vacío si es la primera vez.

3

Crea una nueva clave

Haz clic en + Crear clave API en la esquina superior derecha.

4

Nombra la clave y elige sus scopes

El formulario de creación pide dos datos:

  • Nombre: identifica el uso de la llave, por ejemplo Producción - Mi integración.
  • Scopes: los recursos y permisos que la llave podrá usar (ver Permisos y scopes).

No hay un campo de fecha de expiración en el formulario. El backend sí soporta una expiración opcional, pero hoy no está expuesta en la UI de creación — si no defines una, la llave no expira.

5

Copia la clave de inmediato

Se muestra una sola vez

Fenicia solo devuelve el valor completo de la clave en la respuesta de creación. Ninguna otra pantalla —ni el listado, ni el detalle— vuelve a mostrarlo. Si la pierdes, no hay forma de recuperarla: tendrás que generar una nueva.

6

Guárdala en tu ambiente

Nunca la escribas directo en el código fuente. Léela desde una variable de entorno:

# .env
FENICIA_API_KEY=fkapi_1m8x2z9k_3f9a1c2d4e5f6789abcd0123ef456789
Configuración → Claves API. Desde aquí gestionas todas las API keys de tu cuenta.

Formato real de la key

Todas las API keys que genera Fenicia siguen un único formato, producido por un solo generador en todo el sistema:

fkapi_{timestamp en base36}_{uuid v4 sin guiones}

Ejemplo: fkapi_1m8x2z9k_3f9a1c2d4e5f6789abcd0123ef456789

Límite de llaves por tenant

Cada tenant puede tener máximo 10 API keys activas simultáneamente. Es un límite fijo, hardcoded, que no varía por plan. Si intentas crear una llave número 11 con 10 activas, la creación falla — revoca o elimina alguna llave sin uso antes de crear una nueva.

Revocar vs eliminar

Son dos acciones distintas y ambas existen en el panel:

AcciónQué haceReversible
RevocarMarca la llave como inactiva. Deja de autenticar peticiones de inmediato. El registro permanece en la lista, visible pero inutilizable.Solo por soporte — no hay botón de "reactivar" en el panel.
EliminarBorra el registro de la llave por completo.No — es permanente.

Efecto inmediato

Tanto revocar como eliminar cortan el acceso al instante: cualquier petición que use esa llave después empieza a fallar (ver Autenticación para el shape real del error).

Rotación

No existe un botón de "regenerar" que reemplace el valor de una key existente conservando su identidad. Para llaves de usuario, rotar es un proceso manual:

1

Crea una nueva API key

Con los mismos scopes que la que vas a reemplazar.

2

Despliega la nueva credencial

Actualiza la variable de entorno en todos los servidores o funciones que consumen la API.

3

Revoca la anterior

Una vez confirmado que todo el tráfico usa la nueva llave.

Quién puede gestionar API keys

Hoy, solo el o los owners del tenant pueden crear, listar, revocar o eliminar API keys. Un usuario con rol de administrador o manager —incluso con permisos amplios como settings:*— no tiene acceso a esta gestión: la operación exige el privilegio de owner internamente. Si tu equipo espera delegar esta gestión a un rol "Admin" que no sea el dueño de la cuenta, hoy no es posible.

Buenas prácticas

  • Aplica el principio de mínimo privilegio al elegir scopes: no uses el comodín de todos los recursos para una integración que solo necesita leer pedidos.
  • Nunca incluyas la key en código del cliente, repositorios públicos o logs.
  • Usa variables de entorno o un gestor de secretos, nunca la escribas directo en el código fuente.
  • Como no hay rotación automática, agenda rotaciones manuales periódicas (crear → migrar tráfico → revocar la anterior).
  • Ante cualquier sospecha de filtración, revoca la llave de inmediato — no esperes a confirmar el abuso.

Tip

Si tu integración necesita distintos niveles de acceso (por ejemplo, un proceso que solo lee pedidos y otro que además los actualiza), crea una key por caso de uso en vez de una sola key con todos los permisos.

Siguientes pasos