Guia do produto e da API

Autenticação

Para que serve uma chave

Cada chamada inclui uma chave que pertence ao espaço de trabalho, não a uma pessoa, então ela continua funcionando quando alguém sai. Você cria uma em Conta, Chaves de API: o segredo é exibido uma vez e suas ações são definidas pelos escopos.

Cada solicitação inclui uma chave de API. Você cria uma na tela de chaves de API da sua conta; ela é exibida uma vez na criação e nunca é armazenada de forma legível.

X-PDFgine-Key: pdfgine_live_xxxxxxxxxxxxxxxxxxxxxxxx

Nunca incorpore a chave em um navegador ou aplicativo móvel. Faça as chamadas pelo seu próprio servidor.

Cada chave possui um conjunto de escopos; uma chave que apenas renderiza documentos não pode modificar modelos.

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

Uma chamada que funciona e outra que não

A primeira chamada lista seus modelos. A segunda envia uma chave revogada, e a resposta informa exatamente isso.

cURL

# A chave fica no ambiente, não no código
export PDFGINE_KEY="pdfgine_live_..."

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

Resposta

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"
}

Todo corpo de erro inclui correlationId. Informe-o ao escrever ao suporte para localizar a solicitação nos logs sem adivinhação.

Os problemas mais comuns

A chave vai no cabeçalho X-PDFgine-Key. Um token Authorization: Bearer não é lido, então a chamada responde 401 mesmo se a chave for válida.
401 e 403 significam coisas diferentes. 401 é “não sei quem você é”; 403 é “sei quem você é, mas esta chave não tem esse escopo”: uma chave sem templates:write não pode salvar um modelo. Os escopos são definidos na criação da chave.
O segredo é exibido uma vez. Se for perdido, não há como lê-lo novamente; revogue a chave e crie outra.
Uma chave nunca deve ficar em um navegador ou aplicativo móvel. Tudo o que é enviado a um dispositivo pode ser lido; chame o PDFgine pelo seu próprio servidor.
A revogação vale já na próxima chamada. Implante a nova chave primeiro e depois revogue a antiga; caso contrário, as chamadas em andamento falham.