Authentication

All API requests to badges.ninja require authentication. This page explains how to authenticate your requests.

Base URL

https://api.badges.ninja

All API endpoints are relative to this base URL.

API Key Authentication

The primary authentication method is an API key passed in the X-Api-Key header.

Getting an API Key

From the dashboard:

1. Sign in at badges.ninja.
2. Go to API Keys in the sidebar.
3. Click Create API Key.
4. Copy the key (it is only shown once).

From the API:

API keys can also be managed via the API using your JWT token from the Cognito authentication flow. See the dashboard for the simplest approach.

Using Your API Key

Include the X-Api-Key header in every request:

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

API Key Format

Keys use the bws_ prefix:

bws_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Request Format

• GET requests pass parameters as query strings
• POST and PUT requests send a JSON body with a parameters object
• All responses return JSON with Content-Type: application/json

POST/PUT Request Structure

{
  "parameters": {
    "name": "My Badge",
    "description": "A sample badge"
  }
}

Example Request

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": "My Organization",
      "url": "https://example.com",
      "email": "admin@example.com"
    }
  }'

Example Response

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

Rate Limits

API requests are subject to rate limiting. If you exceed the limit, you receive a 429 Too Many Requests response. Wait a few seconds and retry.

Public Endpoints

Some endpoints do not require authentication. These are the public verification endpoints under /certify-badge/ that allow anyone to verify badge credentials.