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": "[email protected]" }'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, osurl = "https://api.navigatr.app/v1/badge/51/issue"payload = { "recipient_firstname": "John", "recipient_lastname": "Doe", "recipient_email": "[email protected]"}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: "[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' => [ 'Authorization' => 'Bearer ' . 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.
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": "[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.
Need help? Email [email protected] and we will get you unstuck quickly.