Autenticação

A API pública usa chaves de API. Cada requisição leva a chave do blog no header X-API-Key, e essa chave define exatamente qual conteúdo você pode ler.

Como enviar a chave

Inclua o header X-API-Key em toda requisição, inclusive nas de leitura simples:

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

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 não definida.");
  return { "X-API-Key": key };
}

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

Escopo da chave

Uma chave de API é vinculada a um blog. Isso significa que:

• Todas as respostas são automaticamente filtradas para o blog dono da chave — você não passa um blogId nos endpoints públicos.
• Os endpoints retornam apenas conteúdo publicado (status PUBLISHED). Rascunhos e posts agendados nunca são expostos.
• Para servir vários blogs, use uma chave por blog.

Onde obter a chave

A chave de API é gerada e gerenciada no painel da DraftIn, nas configurações do blog. Lá também é possível rotacioná-la (revogar a atual e gerar uma nova) caso suspeite de vazamento.

Quando a autenticação falha

Requisições sem a chave, ou com uma chave inválida, retornam 401 Unauthorized. O corpo segue o formato de erro padrão:

{
  "error": "API Key inválida ou ausente",
  "message": "Forneça uma chave válida no header X-API-Key."
}

Boas práticas

• Mantenha a chave no servidor. Em sites Astro/Next, faça as chamadas no build ou em rotas de servidor; não embuta a chave em JavaScript de cliente.
• Use variáveis de ambiente. Carregue a chave de process.env e nunca a versione no Git.
• Uma chave por ambiente. Separe chaves de desenvolvimento e produção quando possível para limitar o impacto de um vazamento.
• Rotacione ao suspeitar. Se a chave aparecer em um log, commit ou bundle público, rotacione-a imediatamente no painel.
• Cacheie respostas. Conteúdo publicado muda pouco; cachear reduz chamadas e protege contra picos. Veja Rate limits.

Um cliente reutilizável

Centralize a chave e o tratamento de erros em um pequeno cliente — assim cada chamada fica enxuta e consistente:

// draftin.ts — um cliente mínimo reutilizável
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("Chave de API inválida ou ausente.");
    if (!res.ok) throw new Error(`DraftIn API: ${res.status}`);
    return res.json() as Promise<T>;
  }

  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);