Crear y gestionar claves de API

Genera una clave de API, elige sus scopes, ponle caducidad y rótala o revócala: todo lo que necesitas antes de tu primera llamada.

Una clave de API es la credencial de larga duración detrás de cada integración. Nunca la envías en las peticiones habituales: la intercambias una sola vez por un token de acceso de corta duración, y el token hace el trabajo.

Las claves se gestionan en la aplicación, no por la API: deliberadamente no existe ningún endpoint que genere una credencial.

Dónde

Configuración → Claves de API. Visible solo para propietarios y administradores, y solo si tu plan incluye acceso a la API.

Antes de empezar: ¿tu plan incluye acceso a la API?

El acceso a la API se vende por separado del resto de BunnyDoc. Sin él:

la pantalla de Claves de API no te deja crear una clave, y
POST /v1/auth/token devuelve 403 forbidden incluso para una clave que ya exista.

Busca dos entradas en Configuración → Facturación → Recursos:

Recurso	Qué controla
Acceso a la API	Si `/v1` funciona en absoluto, y si puedes generar claves.
Solicitudes de firma por API	Cuántos sobres puedes enviar por la API en cada periodo: una unidad por sobre.

Si falta alguno o está a cero, háblanos antes de empezar a construir.

Crear una clave

Nómbrala por la integración, no por la persona

Zapier — producción, Sincronización de facturación, Sandbox de pruebas. El nombre es cómo la reconocerás cuando la rotes o la revoques meses después, y es lo único que tendrás: la clave en sí no se vuelve a mostrar.

Elige el conjunto de scopes más reducido

Los scopes son por clave. Concede solo lo que la integración vaya a llamar; consulta la tabla de abajo.

Opcionalmente, ponle una caducidad

Déjalo en blanco y la clave no caduca nunca. Pon una fecha futura y la clave deja de funcionar en ese momento, devolviendo el mismo 401 que una clave desconocida. Una caducidad es buena higiene para una clave que entregas a un tercero o que usas en una migración acotada en el tiempo.

Copia la clave de inmediato

La clave tiene el aspecto bd_live_… y se muestra exactamente una vez, al crearla. La guardamos con hash, así que no podemos volver a mostrártela: si la pierdes, rota la clave para generar un secreto nuevo.

Guarda la clave en el servidor

Una clave actúa en nombre de toda tu empresa. Nunca la pongas en un navegador, una app móvil, un repositorio ni ningún cliente que no controles. Cárgala desde una variable de entorno o un gestor de secretos.

Scopes

Un scope permite a una clave hacer algo. Nunca puede permitirle hacer más que la persona que la creó: ambos se intersecan en cada petición, así que si esa persona pierde un permiso en la app, sus claves lo pierden en ese mismo momento.

Scope	Habilita
`templates:read`	`GET /v1/templates`, `GET /v1/templates/{id}`
`contacts:read`	`GET /v1/contacts`
`contacts:write`	`POST /v1/contacts`
`envelopes:send`	`POST /v1/envelopes/from-template`, `GET /v1/envelopes/{id}/signing-links`
`webhooks:read`	`GET /v1/webhooks`, `GET /v1/webhooks/events`
`webhooks:write`	`POST /v1/webhooks`, `DELETE /v1/webhooks/{id}`
`users:read`	`GET /v1/users`

Toda clave necesita al menos un scope. Una integración típica de enviar y seguir necesita templates:read, envelopes:send, webhooks:read y webhooks:write, y nada más.

Dos controles independientes

Llamar a un endpoint requiere tanto el scope en la clave como el permiso correspondiente en su propietario. Una clave con templates:read cuyo propietario no puede leer plantillas en la app recibe 403 forbidden, no un resultado. Si falta el scope obtienes 403 insufficient_scope, así que los dos fallos son fáciles de distinguir.

¿Cuántas claves puedo tener?

Tu plan fija el número de claves activas por empresa. Cuando alcanzas el límite, crear otra se rechaza hasta que revoques una. Las claves revocadas no cuentan.

Usa claves separadas por entorno y por integración: es la única forma de revocar una cosa sin romper el resto.

Rotar una clave

La rotación genera un secreto nuevo en el mismo registro de clave, conservando su nombre, scopes y caducidad. Úsala para higiene programada de credenciales.

La rotación no se puede deshacer:

la clave nueva se muestra una sola vez: cópiala y despliégala;
la clave antigua ya no se puede intercambiar por un token, así que POST /v1/auth/token con ella devuelve 401 invalid_api_key;
los tokens de acceso ya emitidos con el secreto antiguo siguen funcionando hasta que caduquen, hasta una hora.

Así que una rotación es un relevo limpio para tu propio despliegue: termina el despliegue dentro de esa hora y no fallará ninguna petición.

Si una clave se ha filtrado, revócala: no basta con rotarla

La rotación cierra la puerta a tokens nuevos, pero deja válido cualquier token ya emitido con el secreto antiguo durante el resto de su hora. Para cortar el acceso de inmediato, revoca la clave y genera una nueva.

Revocar una clave

Revocar inutiliza la clave de forma permanente, y es la acción que surte efecto de inmediato:

la clave nunca más se puede intercambiar por un token, y
todos los tokens vigentes generados con ella fallan en su siguiente petición, con 401 key_revoked: no hay que esperar a que pase su hora.

Es la respuesta correcta ante una sospecha de filtración, la salida de un colaborador externo o una integración que estás apagando.

Qué debe hacer tu integración ante errores de clave

Recibes	Qué ocurrió	Haz esto
`401 invalid_api_key` en `/auth/token`	La clave es desconocida, revocada, caducada o no es de modo real; no decimos cuál	Deja de reintentar. Revisa la clave en Configuración → Claves de API.
`403 forbidden` en `/auth/token`	El acceso a la API no está en el plan	Deja de reintentar. Es un cambio de facturación, no de código.
`401 invalid_token` en cualquier otra llamada	El token caducó	Intercambia la clave por un token nuevo y reintenta una vez.
`401 key_revoked` en cualquier otra llamada	La clave tras el token fue revocada	Deja de reintentar con el token en caché. Carga la clave de reemplazo.
`403 insufficient_scope`	La clave carece de un scope	Añade el scope a la clave (o genera una que lo tenga).

No generes un token por petición

POST /v1/auth/token está limitado a 20 peticiones cada 15 minutos, por IP, porque una integración sana necesita aproximadamente un token por hora. Guarda el token en caché todo su expires_in y renuévalo poco antes de que caduque.