Welcome to Open Badge Factory V2 REST API documentation!
This guide details the API endpoints, JSON formats, request parameters, and response specifications. Select an HTTP verb to view its corresponding resource information.
Available at PRO level subscription.
This API can also be used for the CanCred Factory platform, powered by Open Badge Factory technology. Simply use the host name factory.cancred.ca instead of openbadgefactory.com.
Authentication with OAuth2 Client Credentials
1. Get your API client_id and client_secret
Login to OBF as a user in admin role and go to Admin tools > API. Generate new client secret and give it an informative description that helps you identify it later. Note that the secret string is shown one time only, you must copy and store it at this point. The client_id string identifies your organisation and it is a required path parameter in most API route URLs.
IMPORTANT: This API is designed for server-to-server communication. OAuth tokens and secret keys must be kept secure and never exposed to end users.
Do NOT share the API keys outside your organisation. We will never ask for the secret key via phone, email, or text.
2. Request an access token
Using credentials you obtained in step one, make a token request (See below for details):
POST /v2/client/oauth2/token
Client credentials can be either included as POST body parameters or in HTTP Basic auth header.
You can use the same access token until it expires. Expiration time is short and you need to fetch a new access token after the old one becomes invalid. Please note that generating new access tokens is limited to one token per ten seconds.
The same client credentials can be used until your subscription to our service ends. You can view the list of generated keys in Admin tools > API and also revoke old credentials if necessary.
3. Test your access token
Include your newly created access token in request Authorization header:
Authorization: Bearer {your access token}
Run a test request:
GET /v1/ping/{$client_id}
Successful request will have return code 200 OK.
Example, using curl:
$ curl -H "Authorization: Bearer $access_token" "https://$hostname/v2/client/$client_id/ping"
More info:
https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/