API Keys

Una API Key autentica tus peticiones a la API de AstrApp desde un servidor, un script o un pipeline, sin sesión de navegador.

Cuándo usar una API Key

Úsala en

Servidores backend.
Scripts y automatizaciones.
Pipelines de CI/CD.
Integraciones de servidor a servidor.

No la uses en

Código de frontend o apps móviles.
Repositorios, logs o capturas de pantalla.
Cualquier lugar donde otra persona pueda leerla.

Una key da el acceso completo de tu cuenta

Hoy ninguna ruta revisa los scopes: cualquier key activa actúa como tú, sobre tu organización activa. Trátala como tu contraseña. Los detalles están en Permisos.

Abre API Keys

En el menú lateral de la app, entra a Cuenta › API Keys y haz clic en Nueva API Key.

Nómbrala y elige la expiración

Nombre de la Key: algo que te diga dónde vive, como “Servidor de producción”.
Expiración: 7 días, 30 días, 90 días (recomendado), 1 año o sin expiración.
Permisos: por defecto viene marcado Acceso completo. Puedes marcar scopes acotados, pero hoy solo quedan como etiqueta.

Copia la key

Haz clic en Crear API Key. La key completa tiene la forma sk_live_ seguida de 64 caracteres hexadecimales. En la lista solo verás su prefijo: sk_live_ y los primeros 8 caracteres.

La key se muestra una sola vez

AstrApp guarda solo un hash de la key. Si la pierdes, crea otra y elimina la anterior.

Usar la key

Manda la key en el header Authorization con el prefijo Bearer. La URL base de la API es https://app.astrapp.lat/api/v1.

bash

curl https://app.astrapp.lat/api/v1/projects \
  -H "Authorization: Bearer $ASTRAPP_API_KEY"

En JavaScript

typescript

const response = await fetch('https://app.astrapp.lat/api/v1/projects', {
  headers: {
    Authorization: `Bearer ${process.env.ASTRAPP_API_KEY}`,
  },
})

const { data, pagination } = await response.json()

En Python

python

import os
import requests

response = requests.get(
    "https://app.astrapp.lat/api/v1/projects",
    headers={"Authorization": f"Bearer {os.environ['ASTRAPP_API_KEY']}"},
)
proyectos = response.json()["data"]

Escribe el header tal cual

El servidor quita exactamente Bearer (con B mayúscula y un espacio) antes de leer la key. bearer en minúsculas o un espacio de más hacen que la key no se reconozca y recibas un 401. El header solo acepta API Keys: un token de sesión ahí también da 401.

No todas las rutas aceptan API Key

Varias rutas leen los datos con la sesión del navegador: con una API Key responden una lista vacía o un 404 en vez de un error de permisos. En Endpoints están marcadas como “Solo sesión”.

Rotar y revocar

Una key vencida, desactivada o eliminada deja de funcionar al instante: la API responde 401 con el mensaje Invalid token or session. Para cambiarla sin cortar el servicio:

Crea una key nueva.
Actualiza tu aplicación con la nueva key.
Verifica que todo funcione.
Elimina la key anterior.

En Cuenta › API Keys, el interruptor de cada key la activa o la desactiva sin borrarla, y el ícono de papelera la elimina para siempre (Eliminar API Key). La lista también muestra la fecha de expiración y el último uso de cada key.

Administrar keys por la API

La pantalla de API Keys usa estas rutas con tu sesión.

GET/api/v1/auth/api-keys

Lista tus keysSolo sesión

POST/api/v1/auth/api-keys

Crea una keySolo sesión

GET/api/v1/auth/api-keys/{keyId}

Detalle de una keySolo sesión

PATCH/api/v1/auth/api-keys/{keyId}

Renombra o desactivaSolo sesión

DELETE/api/v1/auth/api-keys/{keyId}

Elimina la keySolo sesión

GET/api/v1/auth/api-keys/{keyId}/usage

Estadísticas de usoSolo sesión

Con una API Key no administras keys

Estas rutas leen la tabla de keys con tu sesión. Llamadas con una API Key, el listado sale vacío y no puedes crear ni borrar keys: hazlo desde la app.

Cuerpo para crear una key

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre de la key, de 1 a 100 caracteres.
`scopes`	string[]	No	Scopes a guardar con la key. Por defecto ["all"].
`expires_in`	string	No	7d, 30d, 90d, 1y o never. Por defecto 90d.
`expires_at`	string	No	Fecha ISO 8601 exacta de expiración. Si la mandas, reemplaza a expires_in.

La respuesta, con estado 201, trae la key completa en el campo key:

json

{
  "data": {
    "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "name": "Servidor de producción",
    "prefix": "sk_live_1a2b3c4d...",
    "scopes": ["all"],
    "expires_at": "2026-12-21T10:00:00.000Z",
    "created_at": "2026-09-22T10:00:00.000Z",
    "key": "sk_live_<64 caracteres hexadecimales>"
  },
  "message": "API key creada. Guárdala en un lugar seguro, no podrás verla de nuevo."
}

Cambiar una key

PATCH acepta is_active (boolean) y name; manda al menos uno. DELETE borra la key de forma permanente.

Los contadores de uso no se actualizan

La ruta /usage devuelve total_requests y requests_today, pero hoy nada los incrementa y salen en 0. La fecha confiable es last_used_at del listado, que se actualiza en cada petición autenticada con la key.

Buenas prácticas

Nunca publiques tu key: fuera del código fuente, los commits y los logs.
Usa variables de entorno: guárdala en .env y agrega .env a .gitignore.
Una key por servicio: así revocas una sin tumbar las demás.
Ponle expiración: la app recomienda 90 días; las keys sin expiración son menos seguras.
Revisa el último uso: una key que no reconoces o que nadie usa, elimínala.