Autenticación

La API pública usa claves de API. Cada petición lleva la clave del blog en la cabecera X-API-Key, y esa clave define exactamente qué contenido puedes leer.

Cómo enviar la clave

Incluye la cabecera X-API-Key en cada petición, incluso en las de lectura simple:

curl https://api.draftin.io/public/posts \
  -H "X-API-Key: dra_xxxxxxxxxxxxxxxxxxxxxxxxxxx"

await fetch("https://api.draftin.io/public/posts", {
  headers: {
    "X-API-Key": process.env.DRAFTIN_API_KEY,
  },
});

function draftinHeaders(): HeadersInit {
  const key = process.env.DRAFTIN_API_KEY;
  if (!key) throw new Error("DRAFTIN_API_KEY no está definida.");
  return { "X-API-Key": key };
}

await fetch("https://api.draftin.io/public/posts", {
  headers: draftinHeaders(),
});

Alcance de la clave

Una clave de API está vinculada a un blog. Esto significa que:

• Todas las respuestas se filtran automáticamente al blog dueño de la clave — no pasas un blogId en los endpoints públicos.
• Los endpoints devuelven solo contenido publicado (estado PUBLISHED). Los borradores y posts programados nunca se exponen.
• Para servir varios blogs, usa una clave por blog.

Dónde obtener la clave

La clave de API se genera y gestiona en el panel de DraftIn, en la configuración del blog. Allí también puedes rotarla (revocar la actual y generar una nueva) si sospechas de una filtración.

Cuando la autenticación falla

Las peticiones sin la clave, o con una clave inválida, devuelven 401 Unauthorized. El cuerpo sigue el envelope de error estándar:

{
  "success": false,
  "error": {
    "message": "Se requiere clave de API para las rutas públicas",
    "code": "UNAUTHORIZED",
    "type": "authentication",
    "statusCode": 401,
    "retryable": false,
    "requestId": "req_5c26469a-1234-4c8b-9e21-370450bbda3a",
    "docs": "https://docs.draftin.io/errors/UNAUTHORIZED"
  }
}

Buenas prácticas

• Mantén la clave en el servidor. En sitios Astro/Next, haz las llamadas en el build o en rutas de servidor; no incrustes la clave en JavaScript de cliente.
• Usa variables de entorno. Carga la clave desde process.env y nunca la subas a Git.
• Una clave por entorno. Separa las claves de desarrollo y producción cuando sea posible para limitar el impacto de una filtración.
• Rota ante la sospecha. Si la clave aparece en un log, commit o bundle público, rótala de inmediato en el panel.
• Cachea las respuestas. El contenido publicado cambia poco; cachear reduce llamadas y protege ante picos. Consulta Límites de tasa.

Un cliente reutilizable

Centraliza la clave y el manejo de errores en un pequeño cliente — así cada llamada queda concisa y consistente:

// draftin.ts — un cliente mínimo y reutilizable
const BASE = "https://api.draftin.io";

export function createDraftinClient(apiKey: string) {
  async function request<T>(path: string): Promise<T> {
    const res = await fetch(BASE + path, {
      headers: { "X-API-Key": apiKey },
    });
    if (res.status === 401) throw new Error("Clave de API inválida o ausente.");
    if (!res.ok) throw new Error(`DraftIn API: ${res.status}`);
    const { data } = (await res.json()) as { data: T }; // desenvuelve el envelope
    return data;
  }

  return {
    listPosts: (limit = 10, offset = 0) =>
      request(`/public/posts?limit=${limit}&offset=${offset}`),
    getPostBySlug: (slug: string) =>
      request(`/public/posts/slug/${encodeURIComponent(slug)}`),
    listCategories: () => request("/public/categories"),
    listTags: () => request("/public/tags"),
  };
}

// uso
const draftin = createDraftinClient(process.env.DRAFTIN_API_KEY!);
const posts = await draftin.listPosts(5);