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.
• A Personal Access Token. See Personal Access Tokens for API and Integrations to create one.

1. Authenticate with your Personal Access Token

Personal Access Tokens (PATs) are the recommended way to authenticate with the Navigatr API. Once you have a PAT, pass it as a Bearer token in the Authorization header of every request.

Authorization: Bearer YOUR_PAT

No token exchange step is needed. Your PAT does not expire unless you revoke it, so store it securely as an environment variable and reuse it across calls.

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 YOUR_PAT"   -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

Store your PAT as an environment variable (NAVIGATR_PAT) and never hard-code it in your source files.

Python (requests)

import requests, os

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 {os.getenv('NAVIGATR_PAT')}",
    "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 res = await fetch("https://api.navigatr.app/v1/badge/51/issue", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.NAVIGATR_PAT}`,
    "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();

$response = $client->put(
    'https://api.navigatr.app/v1/badge/51/issue',
    [
        'headers' => [
            'Authorization' => 'Bearer ' . getenv('NAVIGATR_PAT'),
            '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. For more information read the Claiming or Viewing Your Badge article.
• A 401 response means your PAT is missing, invalid, or has been revoked. Check Settings > Personal Access Tokens and create a new one if needed.
• For batch issuing, loop through your learner list and call the endpoint once per learner. The rate limit is five requests every two seconds.

Legacy authentication (deprecated)

Before Personal Access Tokens were introduced, the Navigatr API used short-lived bearer tokens generated from your account username and password. This method still works but is no longer recommended. Use PATs for all new integrations.

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 valid for about ten minutes. This approach requires re-authentication before each session and exposes your account credentials in environment variables.

Next Steps

• Personal Access Tokens for API and Integrations covers creating, managing, and revoking your PATs.
• Book a call with our engineering team to discuss complex integrations.
• Need help? Email support@navigatr.app and we will get you unstuck quickly.