Documentación de la API

Autenticación

Cada llamada lleva una clave de API en la cabecera Authorization. No existe ningún otro modo de autenticación.

La cabecera

El esquema es Bearer. Una clave ausente, mal formada, desconocida o revocada devuelve siempre un 401: los cuatro casos se distinguen por el campo code, nunca por el estado HTTP.

HTTP

Authorization: Bearer gaff_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Node.js

const res = await fetch('https://getaff.org/api/v1/me', {
  headers: { Authorization: `Bearer ${process.env.GETAFF_API_KEY}` },
});

if (res.status === 401) {
  // Read the code, not the message: it is the stable part of the contract.
  const { error } = await res.json();
  throw new Error(`GetAff rejected the key: ${error.code}`);
}

Se muestra una sola vez

Solo guardamos una huella de su clave, nunca su valor. Nadie —tampoco nosotros— puede volver a mostrársela después de crearla. Si la pierde, revóquela y cree otra: es una operación rutinaria.

Dónde guardarla

Una clave de API da acceso a sus ingresos. Trátela como una contraseña de producción.

En un gestor de secretos o, en su defecto, una variable de entorno.
Nunca en un repositorio de código, ni siquiera privado: los repositorios privados acaban clonándose.
Nunca en un ticket, un mensaje o una captura de pantalla.
Una clave por integración, para poder revocar una sin detener las demás.

Nunca en un navegador

El prefijo gaff_live_ es reconocible a propósito: los escáneres de secretos lo detectan y salta a la vista en un registro. Es nuestra mejor oportunidad de detectar una fuga mientras aún tiene arreglo.

Si una clave se filtra

Revóquela de inmediato desde la página «Claves de API». La revocación surte efecto en la siguiente llamada. La línea se conserva, marcada como revocada y con su fecha de último uso: así se sabe si la clave se utilizó después de filtrarse.

Claves de API

Ámbitos

Hoy toda clave lleva el ámbito read, el único que existe. El campo ya aparece en la respuesta de /v1/me para que un cliente escrito hoy siga funcionando cuando aparezcan otros ámbitos.