Personal Access Tokens (PATs) are the recommended way to authenticate with the Navigatr API. They give you named, revocable tokens you can manage from your account settings, so you never need to share your account password with third-party tools.
This guide explains how to generate a token, use it in direct API calls, and connect it to tools like Zapier and Moodle.
Prerequisites
A Navigatr account. Learner, provider admin, and community admin accounts can all generate tokens. Start a free trial if you do not have one yet.
1. Create a personal access token
Log in to your Navigatr account.
Go to User Settings → Personal Access Tokens.
Click Create Token.
Give the token a descriptive name: for example, Zapier: badge issuing or Moodle plugin. This makes it easy to identify and revoke later.
Important note: Copy the token immediately. It is only shown once. Store it somewhere safe, such as a password manager or your platform’s secrets store.
You can create multiple tokens, one per integration, so revoking one does not affect the others.
Token permissions and security
A Personal Access Token inherits the full permissions of the account that created it. There is no per-token scope or capability list, so a token issued by a platform admin can do everything that admin can do.
Generate tokens from a dedicated integration account where possible, and avoid creating long-lived tokens from platform admin accounts.
Tokens bypass two-factor authentication. Anyone with the raw key can act as the account without a second factor, so treat the token like a password: store it in a secrets manager and revoke immediately if leaked.
Tokens created from your Settings page do not expire. If you need a time-limited token for a one-off script, call
POST /advanced/v1/personal_access_token/directly with anexpires_atfield.
2. Use your token with the API
Pass your token in the X-Access-Token header on every API request. Here is an example for issuing a badge with the API.
curl -X PUT "https://api.navigatr.app/v1/badge/51/issue" \
-H "X-Access-Token: YOUR_PERSONAL_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"recipient_firstname": "Jane",
"recipient_lastname": "Smith",
"recipient_email": "[email protected]"
}'Replace YOUR_PERSONAL_ACCESS_TOKEN with your token. A successful response returns 200 OK with the issued badge object.
See the full API reference for all available endpoints and request formats.
3. Code examples
Python (requests)
import requests, osPAT = os.getenv("NAVIGATR_TOKEN") # store your token as an environment variableresponse = requests.put(
"https://api.navigatr.app/v1/badge/51/issue",
headers={
"X-Access-Token": PAT,
"Content-Type": "application/json"
},
json={
"recipient_firstname": "Jane",
"recipient_lastname": "Smith",
"recipient_email": "[email protected]"
}
)
print(response.status_code, response.json())Javascript (fetch / node)
const PAT = process.env.NAVIGATR_TOKEN; // store your token as an environment variableconst res = await fetch("https://api.navigatr.app/v1/badge/51/issue", {
method: "PUT",
headers: {
"X-Access-Token": PAT,
"Content-Type": "application/json"
},
body: JSON.stringify({
recipient_firstname: "Jane",
recipient_lastname: "Smith",
recipient_email: "[email protected]"
})
});console.log(await res.json());
4. Connect to Zapier
When adding Navigatr as an action in Zapier, you will be asked to connect your account. Use your Personal Access Token when prompted for an API key or token.
In your Zap, select Navigatr as the action app.
When prompted to connect an account, paste your Personal Access Token into the API Key field.
Continue setting up your Zap as normal.
For a full walkthrough of badge issuing through Zapier, see Getting Started with Zapier and Navigatr.
5. Connect to Moodle
The Navigatr Moodle plugin uses your Personal Access Token to issue badges automatically when learners complete a course.
In Moodle, go to Site administration → Plugins → Local plugins → Navigatr.
Paste your Personal Access Token into the Personal Access Token field.
Click Test Connection to confirm it is working.
Click Save Changes.
For full installation and badge mapping instructions, see Link your Navigatr Badges to a Moodle Course.
6. Manage and revoke tokens
You can view and delete all your tokens at any time from Settings → Personal Access Tokens.
To revoke a token, click Delete next to it. Any integration using that token stops working immediately.
If a token is ever compromised, revoke it straight away and generate a replacement.
We recommend using one token per integration. That way, revoking one does not affect the others.
Tips
Name tokens clearly: Zapier: badge issuing is more useful six months from now than token1.
A
401response means the token is missing, invalid, or has been revoked. Check the value and generate a new one if needed.A
403response means the token is valid but the account does not have permission for that action. Check the role of the account that generated the token.For batch issuing, loop through your learner list and call the endpoint once per record. The public API is rate-limited to 5 requests every 2 seconds per source IP. The Advanced API allows 30 requests every 2 seconds. Add small delays in bulk loops to avoid 429 responses.
Important note: Never put a token directly in your code or commit it to a repository. Use environment variables or a secrets manager.
Next steps
Read the full API reference for all endpoints and request formats.
See Issuing Badges with Navigatr API for more detailed badge issuing examples.
Book a call with our team if you are building a custom integration.
Tip: Need help? Email [email protected] and we will get you unstuck quickly.