About the Navigatr API
Navigatr's API is designed to enable third parties to integrate digital badges
and pathways into their solution.
Our public API is accessible at https://api.navigatr.app/v1/. Refer to the
documentation for a list of endpoints and parameters.
Most endpoints are only available while logged in with a bearer token.
See the Authentication topic for details.
Convention
- A RESTful API exchanging data using JSON requests and responses.
- Requests must be sent with
Content-Type: application/json
- Only accessible over HTTPS for security.
Requests
Some fields use strings, but are required to conform to a schema.
For example, a badge type needs to be one of Badge_Type.
Authentication
We use a dedicated authentication server for handling login requests.
As a result, logging in to the API requires a username and password.
Bearer tokens are short-lived and need to be renewed periodically.
Tokens expire after 5-15 minutes.
Logging in
Call the endpoint /v1/token to get the bearer token.
POST https://api.navigatr.app/v1/token
Data: {
"username": "someone@example.com",
"password": "password"
}
Returns:
{
"access_token": "xxxyyyzzz"
}
When making calls to other endpoints, include this token in the request header:
GET https://api.navigatr.app/v1/user_detail/0
Headers:
- Authorization: Bearer xxxyyyzzz
Python Example
# Get the token
r = requests.get("https://api.navigatr.app/v1/token", data={"username": "someone@example.com", "password": "password"})
token = r.json().get("access_token")
# Try an authenticated endpoint
r = requests.get("https://api.navigatr.app/v1/user_detail/0", headers={"Authorization": f"Bearer {token}"})
print("Hello", r.json().get("firstname"))
Responses
HTTP Response Codes
These are the kinds of HTTP responses you can expect from the API.
| Code |
Reason |
Example |
| 400 Bad Request |
Check your parameters and try again. |
A required parameter was missing. |
| 401 Unauthorized |
Not logged in, or token expired. |
|
| 403 Forbidden |
You don't have the necessary permission to access this content. |
Attempting to view draft content for a provider that doesn't belong to this user. |
| 404 Not Found |
The user does not exist, or the endpoint had a typo. |
|
| 410 Gone |
Deleted content. |
|
| 422 Unprocessible Entity |
Check your data and logic, then try again. |
Attempting to create a badge for a provider that does not exist, or publishing a unpublishable badge. |
| 423 Locked |
The entity is currently being processed and cannot be modified. |
By editing a badge that is still being duplicated. |
Successful responses return 200 Success. In some cases, they may be 202 Accepted depending on context.
If you're lucky to ever encounter a 50x error, please let us know
by raising a support ticket.
Media URLs
If your application or network is required to audit and approve URLs,
the API may link to resources hosted at these domains:
- media.navigatr.app
- images.credly.com
Pagination
If the API response includes a list, the pagination information will be included at the bottom of the response.
{
"items": [
...
],
"total": 37,
"page": 1,
"size": 50
}
Total: the total number of items across all pages.
Page: the current page number as per request. The default is 1. This can be changed to read the data from other pages.
Size: the page size as per defined in the request. This refers to the number of items per page. The default is 50. This can be changed based on requirements in order to receive fewer or more items per page.
