Autenticación

Cada petición lleva la llave del proyecto en el encabezado Authorization:

curl https://api.timbre.cr/internal/v1/issuers \
  -H "Authorization: Bearer timbre_sk_…"

La llave

Se genera con el CSPRNG y se muestra una sola vez. De ahí en adelante solo se guarda su SHA-256: no hay forma de recuperarla, ni para vos ni para nosotros ni para quien tenga un respaldo de la base.

Lleva el prefijo timbre_sk_<ambiente>_ —timbre_sk_sandbox_… o timbre_sk_production_…— para que una fuga sea greppable, la detecten las herramientas de escaneo de secretos, y el ambiente se lea a simple vista sin tener que ir a buscarlo al panel.

Una llave identifica un proyecto. Todo lo que hagas con ella queda dentro de la cuenta de ese proyecto, y toda consulta se filtra por ahí.

Ambientes

Un proyecto está fijado a un ambiente: sandbox o production. No es una bandera que mandás en la petición —cambiar de ambiente significa otro proyecto, con otra llave.

Esa rigidez es a propósito: un parámetro que elige ambiente es un parámetro que alguien manda mal una vez y presenta un documento de prueba como real.

El proyecto de sandbox existe desde que creás la cuenta. El de producción se activa desde el panel, y crearlo no habilita por sí solo ningún documento real: para eso hacen falta además las credenciales de producción de cada contribuyente. Cómo se hace está en Producción.

Límites

Cada proyecto tiene su propio límite de peticiones. Al excederlo la respuesta es 429 con Retry-After en segundos.

Es distinto del tope mensual de documentos que podés finalizar en producción —también 429, pero sin Retry-After, porque no se resuelve esperando unos segundos sino con el próximo mes o con un tope más alto. Sandbox no lo tiene. Errores explica document_limit_reached y cómo consultar cuánto llevás.

Cuando falla

Sin encabezado, con un formato que no sea Bearer <llave>, con una llave que no existe o con una revocada, la respuesta es siempre la misma:

{ "error": "unauthorized", "message": "A valid bearer API key is required" }

Idéntica en los cuatro casos, a propósito: distinguirlos le diría a quien está probando llaves cuál de sus intentos se acercó.