Skip to content

Quick Start

This walks through the simplest way to issue a badge through the API: authenticate, create a user, choose a badge, and issue it.

1. Obtain an access token

Your integration uses OAuth2 client credentials (a client id and client secret) to obtain short-lived access tokens.

API access is available only on plans that include the BadgeCert API, and credentials are visible only to ADMIN users. Log in to BadgeCert, open Settings → Profile → API Information, and copy your client id and client secret.

Request a token with HTTP Basic authentication and grant_type=client_credentials in the form body:

curl -sS -X POST "https://api.badgecert.com/v1/oauth/token" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use the access_token value as a Bearer token on every request below.

2. Create a user

Create the person who will receive the badge (POST /v1/users):

curl -sS -X POST "https://api.badgecert.com/v1/users" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "givenName": "Jane",
    "familyName": "Doe"
  }'

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "membershipStatus": "ACTIVE"
}

Save the user id — you will need it in step 4.

3. List badges and choose one

List badge definitions in your organization (GET /v1/badges):

curl -sS "https://api.badgecert.com/v1/badges" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Safety Certification"
    }
  ]
}

Save the badge id you want to issue — you will need it in step 4.

4. Issue the badge

Issue the badge to the user (POST /v1/issuances), using the user id and badge id from the previous steps:

curl -sS -X POST "https://api.badgecert.com/v1/issuances" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "badgeId": "660e8400-e29b-41d4-a716-446655440001",
    "issueDate": "2026-01-15",
    "issuerName": "Acme Training"
  }'

5. Confirm the result

A successful response returns the new issuance id:

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "badgeId": "660e8400-e29b-41d4-a716-446655440001"
}

The badge has been issued.

6. Where to go next

  • Data Model: Organizations, users, badges, and issuances.
  • API reference (Swagger): Swagger UI for every other operation, filter, and field.