Autenticación

Cada petición a la API se identifica con una API key: una clave que pertenece a un negocio y que lleva sus propios permisos. No hay usuarios ni contraseñas; la clave es la credencial.

Crear una clave

La clave se crea dentro de Olympus, en Configuración → Integraciones → Nueva clave, por un dueño o administrador del negocio. Se muestra una sola vez. El paso a paso, con qué poner en cada campo, está en Crear tu API key.

Trátala como una contraseña

Quien tiene la clave puede emitir facturas con validez tributaria en nombre del negocio. Guárdala en el gestor de secretos de tu sistema, nunca en el código ni en el repositorio, y no la envíes por correo ni por chat. Si sospechas que se filtró, revócala: el corte es inmediato.

Usar la clave

Envíala en la cabecera X-API-Key de cada petición:

curl

curl https://olympus.atharix.com/api/v1/me \
  -H "X-API-Key: dlt_tu_clave_aqui"

Python

import httpx

client = httpx.Client(
    base_url="https://olympus.atharix.com/api/v1",
    headers={"X-API-Key": os.environ["OLYMPUS_API_KEY"]},
    timeout=20,
)
cuenta = client.get("/me").json()

Node

const olympus = async (path, init = {}) =>
  fetch(`https://olympus.atharix.com/api/v1${path}`, {
    ...init,
    headers: {
      "X-API-Key": process.env.OLYMPUS_API_KEY,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });

const cuenta = await (await olympus("/me")).json();

PHP

$ch = curl_init("https://olympus.atharix.com/api/v1/me");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("OLYMPUS_API_KEY")],
]);
$cuenta = json_decode(curl_exec($ch), true);

También se acepta Authorization: Bearer dlt_… si tu cliente HTTP ya está montado sobre ese esquema.

Permisos (scopes)

Una clave solo puede hacer aquello para lo que se le dio permiso. Da siempre el mínimo necesario:

Scope	Permite
invoices:write	Emitir facturas, reintentar envíos y reenviar correos
invoices:read	Consultar y listar facturas, descargar PDF y XML
documents:read	Consultar, listar y descargar notas, retenciones, guías y liquidaciones; cualquier comprobante por clave de acceso
documents:write	Emitir notas de crédito y débito, retenciones, guías de remisión y liquidaciones de compra (Ecuador)
contacts:write	Crear y actualizar clientes (próximamente)
catalog:read	Consultar productos y tarifas (próximamente)

GET /me, GET /establishments y GET /catalogs/… funcionan con cualquier clave válida.

Si una clave intenta algo fuera de sus permisos recibe un 403:

{
  "error": {
    "code": "insufficient_scope",
    "message": "La API key no tiene permiso para esta operación.",
    "details": { "required": ["invoices:write"], "granted": ["invoices:read"] }
  }
}

Restricciones adicionales

Al crear o editar una clave puedes acotarla más:

• IPs permitidas. Una lista de direcciones o rangos CIDR (203.0.113.7, 10.0.0.0/24). Desde cualquier otra dirección la clave no funciona. Recomendado si tu sistema tiene IP fija.
• Caducidad. Una fecha a partir de la cual la clave deja de servir. Útil para integraciones temporales o pruebas de un tercero.
• Establecimiento por defecto. El establecimiento y el punto de emisión que se usan cuando el payload no los indica. Práctico si cada sistema factura desde una sucursal distinta.
• Límite de peticiones. Un tope por minuto propio de esa clave, por debajo del general.

Rotar una clave

Rotar crea una clave nueva y deja la anterior viva durante un periodo de gracia (24 horas por defecto, hasta 7 días). Así puedes desplegar el cambio sin cortar la facturación:

1. En Configuración → Integraciones, pulsa Rotar en la clave.

2. Copia la clave nueva y despliégala en tu sistema.

3. Cuando el despliegue esté confirmado, revoca la anterior sin esperar al final del plazo.

Al terminar el periodo de gracia, la clave vieja deja de funcionar sola.

Revocar una clave

Revocar es inmediato e irreversible: la siguiente petición con esa clave recibe un 401. No se puede deshacer; si te equivocas, crea una nueva.

{
  "error": {
    "code": "api_key_revoked",
    "message": "Esta API key fue revocada. Genera una nueva desde Configuración → Facturación electrónica → Integraciones."
  }
}

Errores de autenticación

Código	Qué pasó	Qué hacer
invalid_api_key	Falta la cabecera o la clave no existe	Revisa que envías X-API-Key y que la clave está completa
api_key_revoked	La clave fue revocada	Crea una nueva desde la web
api_key_expired	Pasó su fecha de caducidad	Rota la clave o amplía la caducidad
api_key_disabled	La clave está desactivada	Vuelve a activarla desde la web
ip_not_allowed	Tu IP no está en la lista de la clave	Añade la IP o quita la restricción
insufficient_scope	La clave no tiene ese permiso	Añade el scope que indica details.required

Qué ve el negocio

Cada petición queda registrada: fecha, clave, endpoint, código de respuesta, duración y request_id. El negocio lo consulta en Configuración → Integraciones → Registro de peticiones. Los cambios en las claves (creación, edición, rotación, revocación) también quedan auditados con su autor.

Las claves nunca aparecen en claro: ni en la lista, ni en el registro, ni en los correos.