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 the X-Access-Token header on every request.
X-Access-Token: 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 "X-Access-Token: YOUR_PAT" \
-H "Content-Type: application/json" \
-d '{
"recipient_firstname": "John",
"recipient_lastname": "Doe",
"recipient_email": "[email protected]"
}'
A successful call returns 200 OK with the issued badge object.
Code examples
Important note: Store your PAT as an environment variable (NAVIGATR_PAT) and never hard-code it in your source files.
Python (requests)
import os
import requests
url = "https://api.navigatr.app/v1/badge/51/issue"
payload = {
"recipient_firstname": "John",
"recipient_lastname": "Doe",
"recipient_email": "[email protected]"
}
headers = {
"X-Access-Token": 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: {
"X-Access-Token": process.env.NAVIGATR_PAT,
"Content-Type": "application/json"
},
body: JSON.stringify({
recipient_firstname: "John",
recipient_lastname: "Doe",
recipient_email: "[email protected]"
})
});
console.log(await res.json());
PHP (Guzzle)
$client = new \GuzzleHttp\Client();
$response = $client->put(
'https://api.navigatr.app/v1/badge/51/issue',
[
'headers' => [
'X-Access-Token' => getenv('NAVIGATR_PAT'),
'Content-Type' => 'application/json'
],
'json' => [
'recipient_firstname' => 'John',
'recipient_lastname' => 'Doe',
'recipient_email' => '[email protected]'
]
]
);
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.
If the badge has a minimum score, the API may return 202 Accepted with a
"Score is too low"detail instead of issuing the badge. Always check the response body, not just the status code.Keep request payloads small. The public API does not enforce a body size limit, but very large payloads can time out or fail silently at the proxy layer.
Note: For batch issuing, loop through your learner list and call the endpoint once per learner. The rate limit is five requests every two seconds.
Important note: Header-based authentication using x-username and x-password (accepted by GET /v1/badge/ and GET /v1/badge_assertion/ list endpoints) will be removed at the end of July 2026. Migrate any integrations using this pattern to a Personal Access Token before then. The form-login endpoint POST /v1/token described below is still supported.
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": "[email protected]",
"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.
Tip: Need help? Email [email protected] and we will get you unstuck quickly.