Claves de API

Las claves de API te permiten acceder a la API REST de badges.ninja de forma programática. Úsalas para automatizar la creación, emisión y gestión de insignias desde tus propias aplicaciones.

Crear una clave de API

1. Abre la página API Keys desde la barra lateral.
2. Pulsa Create API Key. Se abre un formulario en línea:

3. Ponle un nombre a la clave y pulsa Create. La clave completa se muestra una sola vez en un banner verde:

4. Copia la clave de inmediato: la clave completa solo se muestra una vez. Si la pierdes, tendrás que crear una nueva. Después de cerrar el banner, el panel solo muestra el prefijo de la clave (p. ej. bws_a1b2c3d4...); la clave completa permanece almacenada en el servidor para autenticar tus solicitudes:

Cada fila también muestra cuándo se creó la clave y, una vez usada, una marca de tiempo de último uso para que puedas detectar claves sin actividad.

Ámbitos de acceso

Al crear una clave puedes hacerla de solo lectura o dejarla con acceso completo:

Ámbito	Permite
Acceso completo (predeterminado)	Lectura y escritura: listar datos y crear, emitir, actualizar o eliminar.
Solo lectura	Únicamente solicitudes GET seguras. Cualquier solicitud que modifique datos (POST, PUT, PATCH, DELETE) se rechaza con 403 Forbidden.

Usa una clave de solo lectura para integraciones que únicamente necesiten leer tus datos (informes, paneles, copias de seguridad), de modo que una clave filtrada no pueda cambiar nada. Marca Read-only key en el formulario de creación; las claves de solo lectura muestran una insignia Read-only en la lista. Las claves creadas antes de que existieran los ámbitos conservan el acceso completo.

Formato de la clave

Las claves de API usan el prefijo bws_ seguido de una cadena hexadecimal de 32 caracteres:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Usar claves de API en las solicitudes

Incluye la clave de API en el encabezado X-Api-Key de cada solicitud a la API:

curl -X GET https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here"

Consulta la página de Autenticación para ver todos los detalles sobre la autenticación de la API.

Límites de claves por plan

La cantidad de claves de API que puedes crear depende de tu plan:

Plan	Límite de claves de API
Free	1
Starter ($9/mo)	5
Pro ($29/mo)	20

Caducidad de las claves

Cada clave de API caduca un año después de su creación. Cuando una clave caduca, deja de autenticar solicitudes, exactamente como si se hubiera eliminado. Crea una clave nueva antes de que la anterior venza para evitar interrupciones.

Eliminar una clave

1. Abre la página API Keys.
2. Busca la clave que quieres eliminar.
3. Pulsa Delete.
4. Confirma la eliminación.

Una vez eliminada, la clave deja de funcionar de inmediato. Cualquier aplicación que use esa clave recibirá errores de autenticación.