Autenticación

AstroAPI admite varios métodos de autenticación según vuestro caso de uso.

Autenticación con Clave de API

Las claves de API son el método recomendado para la comunicación servidor a servidor.

Obtener una Clave de API

1. Iniciad sesión en el Panel de AstroAPI
2. Navegad a Configuración > Claves de API
3. Haced clic en Crear Clave de API
4. Configurad los permisos y límites de uso
5. Copiad la clave generada (no se mostrará de nuevo)

Usar Claves de API

Incluid vuestra clave de API en la cabecera X-Api-Key:

curl -X GET "https://api.astroapi.cloud/api/calc/natal" \
  -H "X-Api-Key: ak_live_xxxxxxxxxxxx"

Permisos de Claves de API

Las claves de API pueden limitarse a permisos específicos:

Permiso	Descripción
calc:read	Acceso a los endpoints de cálculo
content:read	Acceso a los endpoints de contenido e interpretaciones
chart:read	Acceso a los endpoints de renderizado de cartas
modules:read	Acceso a los módulos adquiridos

Roles

AstroAPI utiliza control de acceso basado en roles dentro de las organizaciones:

Rol	Descripción
owner	Acceso completo a todas las funcionalidades de la organización
manager	Puede gestionar usuarios, facturación y contenido
member	Acceso básico a cálculos y lectura de contenido

Permisos por Rol

Permiso	owner	manager	member	Descripción
org:create	✅			Crear organización
org:read	✅	✅	✅	Leer organización
org:update	✅	✅		Actualizar organización
org:users:read	✅	✅		Leer usuarios
org:users:create	✅	✅		Invitar usuarios
org:users:update	✅	✅		Actualizar usuarios
org:users:delete	✅	✅		Eliminar usuarios
billing:read	✅	✅		Ver facturación
billing:manage	✅	✅		Gestionar facturación
content:read	✅	✅	✅	Leer contenido
content:create	✅	✅		Crear contenido
content:update	✅	✅		Actualizar contenido
content:delete	✅	✅		Eliminar contenido
content:custom-copy	✅	✅	✅	Crear copias personalizadas
content:restore	✅	✅		Restaurar contenido
calc:use	✅	✅	✅	Usar endpoints de cálculo
chart:use	✅	✅	✅	Usar endpoints de cartas
modules:read	✅	✅	✅	Leer información de módulos
admin:access	✅			Acceso de administrador

Contexto de Organización

Para aplicaciones multitenant, las claves de API están vinculadas a organizaciones. El contexto de organización se aplica automáticamente según la clave de API utilizada.

Restricciones de Dominio

Las claves de API pueden configurarse con restricciones de dominio para limitar qué sitios web pueden utilizarlas:

• example.com — Coincidencia exacta de dominio
• *.example.com — Todos los subdominios
• * — Permitir todos los dominios (no recomendado)

Configurad las restricciones de dominio en el panel al crear o editar una clave de API.

Limitación Importante

Las restricciones de dominio solo protegen contra el uso indebido desde el navegador. Se basan en las cabeceras Origin y Referer, que los navegadores imponen pero que pueden falsificarse fácilmente fuera del navegador (por ejemplo, con curl, scripts o código del lado del servidor).

Uso en Cliente vs. Servidor

Servidor a Servidor (Recomendado)

Para aplicaciones en producción, utilizad siempre las claves de API en vuestro servidor backend:

┌─────────────┐      ┌─────────────────┐      ┌─────────────┐
│  Navegador  │ ───► │  Vuestro Backend│ ───► │  AstroAPI   │
│ (sin claves)│      │ (clave API aquí)│      │             │
└─────────────┘      └─────────────────┘      └─────────────┘

Este enfoque:

• Mantiene vuestra clave de API segura y oculta
• Permite añadir vuestra propia capa de autenticación
• Evita que los usuarios finales extraigan la clave de API
• Permite la firma de solicitudes y medidas de seguridad adicionales

Uso en Cliente / Navegador

Si debéis utilizar claves de API directamente en el navegador (por ejemplo, widgets embebidos en sitios estáticos), tened en cuenta estas limitaciones:

• Las claves de API son visibles en el código fuente JavaScript y en las peticiones de red
• Cualquiera puede extraer la clave de vuestro sitio web
• Las restricciones de dominio solo impiden que otros sitios web utilicen vuestra clave mediante JavaScript — no impiden que alguien copie la clave y la use en otro lugar

Para el uso en cliente, recomendamos:

• Activar las restricciones de dominio
• Establecer límites de uso estrictos
• Usar tiempos de expiración cortos
• Monitorizar el uso para detectar anomalías

Responsabilidad del Cliente

Importante

Sois responsables de la seguridad y el uso de vuestras claves de API.

Todas las solicitudes de API realizadas con vuestra clave de API cuentan contra vuestra cuota y se facturan a vuestra cuenta, independientemente de si las realizasteis vosotros o alguien que obtuvo vuestra clave.

Si exponéis una clave de API en el código del cliente y es usada de forma indebida, sois responsables del uso y los costes resultantes. AstroAPI no puede distinguir entre solicitudes legítimas y solicitudes no autorizadas realizadas con una clave de API válida.

Para minimizar el riesgo:

1. Utilizad la comunicación servidor a servidor siempre que sea posible
2. Nunca incluyáis claves de API en sistemas de control de versiones
3. Rotad las claves inmediatamente si sospecháis que han sido comprometidas
4. Configurad alertas de uso para detectar picos inesperados

Buenas Prácticas de Seguridad

• Utilizad la comunicación servidor a servidor para aplicaciones en producción
• Nunca expongáis claves de API en el código del cliente a menos que sea absolutamente necesario
• Rotad las claves de API periódicamente
• Usad los permisos mínimos necesarios
• Activad las restricciones de dominio para claves del lado del cliente
• Estableced límites de uso apropiados
• Supervisad el uso de las claves de API en el panel