Autenticación

Todas las solicitudes a la API de badges.ninja requieren autenticación. Esta página explica cómo autenticar tus solicitudes.

URL base

https://api.badges.ninja

Todos los endpoints de la API son relativos a esta URL base.

Autenticación con clave API

El método principal de autenticación es una clave API que se envía en la cabecera X-Api-Key.

Obtener una clave API

Desde el panel:

1. Inicia sesión en badges.ninja.
2. Ve a Claves API en la barra lateral.
3. Haz clic en Crear clave API.
4. Copia la clave (solo se muestra una vez).

Desde la API:

Las claves API también pueden gestionarse vía API usando tu token JWT del flujo de autenticación de Cognito. Consulta el panel para el enfoque más sencillo.

Usar tu clave API

Incluye la cabecera X-Api-Key en cada solicitud:

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

Formato de la clave API

Las claves usan el prefijo bws_:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Formato de solicitud

• Las solicitudes GET pasan parámetros como query strings
• Las solicitudes POST y PUT envían un cuerpo JSON con un objeto parameters
• Todas las respuestas devuelven JSON con Content-Type: application/json

Estructura de solicitud POST/PUT

{
  "parameters": {
    "name": "Mi insignia",
    "description": "Una insignia de ejemplo"
  }
}

Solicitud de ejemplo

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "Mi organización",
      "url": "https://example.com",
      "email": "admin@example.com"
    }
  }'

Respuesta de ejemplo

{
  "statusCode": 200,
  "info": {
    "issuerId": "https://api.badges.ninja/certify-badge/issuer/abc123-def456"
  }
}

Límites de tasa

Las solicitudes a la API están sujetas a limitación de tasa. Si la superas, recibirás una respuesta 429 Too Many Requests. Espera unos segundos y reintenta.

Endpoints públicos

Algunos endpoints no requieren autenticación. Son los endpoints públicos de verificación bajo /certify-badge/ que permiten a cualquiera verificar las credenciales de una insignia.