Autenticación

Para qué sirve una clave

Cada llamada incluye una clave que pertenece al espacio de trabajo, no a una persona, por lo que sigue funcionando si alguien se va. Se crea en Cuenta, Claves API: el secreto se muestra una vez y sus permisos se fijan mediante los ámbitos asignados.

Cada solicitud incluye una clave API. Puedes crearla en la pantalla de claves API de tu cuenta; se muestra una sola vez al crearla y nunca se almacena de forma legible.

X-PDFgine-Key: pdfgine_live_xxxxxxxxxxxxxxxxxxxxxxxx

Nunca incluyas la clave en un navegador ni en una aplicación móvil. Realiza las llamadas desde tu propio servidor.

Cada clave incluye un conjunto de permisos; una clave que solo renderiza documentos no puede modificar plantillas.

templates:read   templates:write   documents:render
previews:manage  assets:read       assets:write
usage:read       api-keys:manage

Una llamada que funciona y otra que no

La primera llamada lista tus plantillas. La segunda envía una clave revocada y la respuesta lo indica expresamente.

# La clave está en el entorno, no en el código
export PDFGINE_KEY="pdfgine_live_..."

curl -i https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized request",
  "status": 401,
  "detail": "The API key is invalid.",
  "correlationId": "0123b82d0a59e8b196a783af0e0e86bc"
}

Todos los cuerpos de error incluyen un correlationId. Inclúyelo cuando escribas a soporte para que puedan encontrar la solicitud en los registros sin adivinar.

Los errores más habituales

• La clave se envía en la cabecera X-PDFgine-Key. No se lee ningún token Authorization: Bearer, por lo que la llamada responde 401 aunque la clave sea válida.
• 401 y 403 significan cosas distintas. 401 es «no sé quién eres»; 403 es «te conozco, pero esta clave no tiene ese permiso»: una clave sin templates:write no puede guardar una plantilla. Los permisos se fijan al crear la clave.
• El secreto se muestra una sola vez. Si se pierde, no hay forma de volver a leerlo; revoca esa clave y crea otra.
• Una clave nunca debe estar en un navegador ni en una aplicación móvil. Todo lo que se envía a un dispositivo puede leerse; llama a PDFgine desde tu propio servidor.
• La revocación se aplica desde la siguiente llamada. Despliega primero la nueva clave y después revoca la anterior; de lo contrario, fallarán las llamadas en curso.