Issuing Badges with Navigatr API

Streamline badge issuing and integrations with secure API calls using the Navigatr API.

Prerequisites

• Admin account on Navigatr. Start a free trial.
• A published badge. Follow the badge creation guide.

1. Get an access token

You can create a short-lived bearer token in the Admin UI or with the API (see the Token API endpoint):

curl -X POST "https://api.navigatr.app/v1/token" \
  -H "Content-Type: application/json" \
  -d '{
        "username": "someone@example.com",
        "password": "your_password"
      }'

The response contains an access_token that is valid for about ten minutes. Store it securely.

2. Send the PUT /v1/badge/{badge_id}/issue request

See the Issue Badge endpoint for the full specification.

Find your badge ID in the Admin dashboard or in the badge URL, for example: https://navigatr.app/badge/3425/digital-badge-basics (3425).

curl -X PUT "https://api.navigatr.app/v1/badge/51/issue" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
        "recipient_firstname": "John",
        "recipient_lastname":  "Doe",
        "recipient_email":     "john.doe@example.com"
      }'

A successful call returns 200 OK with the issued badge object.

Code Examples

The example code snippets below will help you get started quickly.

Python (requests)

import requests, json, os

token = requests.post(
    "https://api.navigatr.app/v1/token",
    json={"username": os.getenv("NAVIGATR_USER"),
          "password": os.getenv("NAVIGATR_PASS")}
).json()["access_token"]

url = "https://api.navigatr.app/v1/badge/51/issue"
payload = {
    "recipient_firstname": "John",
    "recipient_lastname": "Doe",
    "recipient_email": "john.doe@example.com"
}
headers = {"Authorization": f"Bearer {token}",
           "Content-Type": "application/json"}

response = requests.put(url, json=payload, headers=headers)
print(response.status_code, response.json())

JavaScript (fetch / Node)

import fetch from "node-fetch";

const { NAVIGATR_USER, NAVIGATR_PASS } = process.env;

const { access_token } = await fetch("https://api.navigatr.app/v1/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ username: NAVIGATR_USER, password: NAVIGATR_PASS })
}).then(r => r.json());

const res = await fetch("https://api.navigatr.app/v1/badge/51/issue", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    recipient_firstname: "John",
    recipient_lastname:  "Doe",
    recipient_email:     "john.doe@example.com"
  })
});

console.log(await res.json());

PHP (Guzzle)

$client = new \GuzzleHttp\Client();

$token = json_decode($client->post(
    'https://api.navigatr.app/v1/token',
    ['json' => [
        'username' => getenv('NAVIGATR_USER'),
        'password' => getenv('NAVIGATR_PASS')
    ]]
)->getBody(), true)['access_token'];

$response = $client->put(
    'https://api.navigatr.app/v1/badge/51/issue',
    [
        'headers' => [
            'Authorization' => 'Bearer ' . $token,
            'Content-Type'  => 'application/json'
        ],
        'json' => [
            'recipient_firstname' => 'John',
            'recipient_lastname'  => 'Doe',
            'recipient_email'     => 'john.doe@example.com'
        ]
    ]
);

echo $response->getStatusCode();

Tips and Troubleshooting

• Use a sandbox badge first to avoid accidental live issuing.
• The email address must be valid or the learner will not receive the badge claim email.
• Capture consent from each learner before issuing their badge.
• Upon issuance, the learner receives an email from Navigatr containing a claim link. If they do not yet have an account, they can set a password, create their account, and claim the badge in one step. Share the learner claim guide.
• A 401 response means the token is missing or invalid.
• For batch issuing, loop through your learner list and call the endpoint once per learner. The rate limit is five requests every two seconds.

Next Steps

• Book a call with our engineering team to discuss complex integrations.
• Need help? Email support@navigatr.app and we will get you unstuck quickly.