TABLE OF CONTENTS

• About our API
  • Who can use the OBF API?
  • How do I get my API credentials?
  • How does authentication work?
  • Can I test whether my API connection works?
  • What happens when my token expires?
  • Are dates and times in a particular format?
  • Can I use the same credentials for CanCred Factory?
• Badge creation and issuing
  • Can I create badges through the API?
  • How do I find the badge_id of a badge?
  • Can I issue badges automatically?
  • Does the API prevent issuing the same badge twice to the same person?
  • Can I control the notification email?
  • Can I set an expiry date?
  • What is api_consumer_id and why is it required?
  • Can I attach evidence to an issued badge?
  • Can I use the API with sub-organisations?
  • Can I issue badges on the blockchain through the API?
• Retrieving issued badges
  • Can I retrieve information about issued badges?
  • Can I retrieve badges issued to a specific recipient?
    • Can I retrieve the learner’s public badge page URL?
  • Can I retrieve the Open Badges 3.0 assertion URL?
  • Can I revoke a badge through the API?
  • Can I report on issuing by course or cohort?
  • How does paging work?
• Badge applications
  • Can I retrieve badge applications through the API?
  • Can I retrieve the questions and answers submitted in a badge application form?
• Badge images and external platforms
  • Can I retrieve the badge image through the API?
  • Can I display OBF badges inside another platform?
• PDF and downloadable formats
  • Can I retrieve the PDF version of an issued badge through the API?
• Statuses
  • What do approved, accepted and unknown mean?
  • How reception statuses appear in the API?
  • Issued badge statuses
  • Badge applications have four statuses
• Performance and rate limits
  • What is the API rate limit?
• Badge resources and formats
  • Where can developers find the complete API specification?

About our API

Open Badge Factory provides a REST API that allows organisations to integrate badge creation, issuing and badge data into external platforms such as LMSs, LXPs, HR systems or custom applications.

The API uses OAuth2 Client Credentials for server-to-server authentication.

For complete endpoint definitions, JSON formats, parameters and response specifications, refer to the OBF API v2 technical documentation.

Who can use the OBF API?

The API v2 is available with an Open Badge Factory Pro subscription.

How do I get my API credentials?

Log in to Open Badge Factory as an administrator and go to Admin tools > API. 

From there, you can generate a client_id and client_secret.

The secret is displayed only once, so it must be stored securely.

API credentials are intended for server-to-server communication and must never be exposed to badge recipients or other end users.

How does authentication work?

API v2 uses OAuth2 Client Credentials. 

Your application first requests an access token using POST /v2/client/oauth2/token. The access token is then included in subsequent API requests as a Bearer token.

Tokens are short-lived. Reuse a token until it expires rather than requesting a new one for every API call. The token endpoint accepts one request per 10 seconds per organisation.

Can I test whether my API connection works?

Yes. Once authenticated, you can test the connection using GET /v2/client/{client_id}/ping. A successful request returns HTTP status 200 OK.

What happens when my token expires?

Requests made with an expired token are answered with HTTP status 401 Unauthorized and a WWW-Authenticate header. Request a new token and retry the call once. Any other rejection returns 403 Forbidden and will not be fixed by retrying.

Are dates and times in a particular format?

Yes. All timestamps are Unix epoch seconds (UTC): in responses, in filter parameters such as begin and end, and in request fields such as expires_on.

Can I use the same credentials for CanCred Factory?

No. Credentials and access tokens belong to one host, openbadgefactory.com or factory.cancred.ca. The API is otherwise identical; use the host your organisation is registered on.

Badge creation and issuing

Can I create badges through the API?

Yes. API v2 provides endpoints for creating and managing badge classes.

When creating or updating badge classes through the API, badge images must currently be provided in PNG format (refer to the badge specification: Creating a new badge).

How do I find the badge_id of a badge?

GET /v2/badge/{client_id} lists your published badges with their ids, names, descriptions and image URLs.

The API does not search badges by name, so match the name on your side, or show the list to a user and let them pick. Store the badge_id with your course or rule rather than the name: names change, ids do not.

Draft badges are left out unless you pass draft=true.

Can I issue badges automatically?

Yes. Badges can be issued from an external application through the API.

For example, an LMS, LXP or HR platform can issue an Open Badge Factory badge automatically when a learner completes a course or meets predefined criteria.

Does the API prevent issuing the same badge twice to the same person?

No. Issuing the same badge to the same email address twice creates two badges and sends two emails.

Before issuing, check who already holds the badge with GET /v2/event/{client_id}/recipient?badge_id={badge_id} and leave those recipients out. This also makes it safe to re-run a batch that failed halfway.

Can I control the notification email?

Yes. Setting send_email to false issues the badges without emailing anyone. The recipients then reach their badges through the receive_url returned by the recipient endpoint; delivering that link is up to you.

The email_message object (subject, body, link_text and footer) replaces the badge’s stored message for that issuing event. Messages are sent as written.

Can I set an expiry date?

Yes. Set expires_on in the issue request as a Unix timestamp. Without it the badge never expires.

The badge’s own default expiry period is informational and is not applied automatically; the integration must send the timestamp.

What is api_consumer_id and why is it required?

It is a fixed name for your integration, sent with every issue request, for example my-lms.

It labels the issuing events you create and is a filter in the event and recipient endpoints, so badges issued by your integration can be told apart from those issued in the OBF UI or by other integrations.

Can I attach evidence to an issued badge?

Yes. Each recipient in the issue request may carry an evidence list, and evidence can be added to an already issued badge with PUT /v2/event/{client_id}/{event_id}/evidence/{assertion_id}. Evidence is read with GET on the same path.

Can I use the API with sub-organisations?

Yes. API v2 supports integrations involving sub-organisations, including selecting the appropriate issuing organisation when issuing badges.

Sub-organisations are called issuer aliases in the API. GET /v2/client/{client_id}/alias lists them, and passing one of their ids as client_alias_id when issuing puts the sub-organisation’s name and contact details on the credential in place of the organisation’s. Each badge lists the sub-organisations it may be issued with.

Can I issue badges on the blockchain through the API?

Yes, if blockchain anchoring is enabled for the badge.

The API itself does not have any blockchain-specific features: there is no dedicated endpoint or parameter for blockchain issuing. However, if blockchain anchoring is enabled for a badge in Open Badge Factory, it applies to all issuing methods, including badges issued through API v2.

Retrieving issued badges

Can I retrieve information about issued badges?

Yes. API v2 provides event and recipient endpoints for retrieving information about issued badges.

Depending on the endpoint, issued badge information can include data such as:

• issuing and expiration dates;
• badge ID;
• issuing organisation or sub-organisation;
• recipient badge page URL;
• Open Badges assertion JSON URL;
• reception flags (received, in_passport, pdf_downloaded).

Can I retrieve badges issued to a specific recipient?

Yes. Issuing events can be searched using several criteria through API v2.

For integrations that need to retrieve badges associated with a specific recipient, identified by email address, use the API filtering/search options rather than repeatedly retrieving the full issuing dataset.

To retrieve all badges issued to one email address, use the email filter of the recipient endpoint: GET /v2/event/{client_id}/recipient?email=some.email@example.com. The filter is an exact match on the whole address.

Can I retrieve the learner’s public badge page URL?

Yes. The recipient data returned by GET /v2/event/{client_id}/recipient contains two URLs for each issued badge:

• receive_url is the recipient’s personal badge page, the same link that is sent in the issuing email. This is where the recipient accepts and downloads the badge.
• assertion_json_url is the public Open Badges 3.0 credential as JSON (see the next question). The same address without the .json suffix shows the credential as a public, human-readable page: https://openbadgefactory.com/obv3/credentials/{assertion_id}

This public credential URL can be used by an external platform to allow learners to view the complete credential. Keep receive_url for the recipient themselves.

Can I retrieve the Open Badges 3.0 assertion URL?

Yes. The recipient endpoint can return the URL of the hosted Open Badges 3.0 assertion JSON associated with an issued badge. This machine-readable credential can be used by external applications to verify or process the badge.

The assertion JSON URL is returned in the assertion_json_url attribute of the recipient data, using GET /v2/event/{client_id}/recipient.

Can I revoke a badge through the API?

Yes. PUT /v2/event/{client_id}/{event_id}/revoke takes the recipient email addresses to revoke within one issuing event.

Revocation cannot be undone, although the badge can be issued to the person again. No email is sent to the recipient on revocation.

Can I report on issuing by course or cohort?

Yes. Store your own keys in log_entry when issuing, for example {"course_id": "DL-101"}, then filter the event and recipient endpoints with log_entry=course_id:DL-101.

begin and end bound the period as Unix timestamps, and api_consumer_id restricts the result to badges issued by your integration.

How does paging work?

List endpoints return a result array and a total. Page with limit (at most 1000) and offset until you have total rows.

total counts every match, not just the page, so a request with limit=1 is a cheap way to count.

Badge applications

Can I retrieve badge applications through the API?

Yes. API v2 provides access to badge application data.

Applications can be searched with GET /v2/earnablebadge/{client_id}/application, filtered for example by status or applicant email, and a single application is returned by GET /v2/earnablebadge/{client_id}/{earnable_id}/{application_id}.

Can I retrieve the questions and answers submitted in a badge application form?

Yes. The single application endpoint returns the application form as a form array. Each field carries the question (name, type and, for option fields, options) and the applicant’s answer in value. For checkbox, radio and select fields, value lists the selected options in brackets, for example [A], [B]; an empty value means the field was not answered.

The same submission is also available as rendered HTML in form_html, and earlier revision rounds of the application through the revision endpoint.

Badge images and external platforms

Can I retrieve the badge image through the API?

Yes. For an issued badge, the badge image URL can be found in the Open Badges 3.0 assertion JSON in credentialSubject.achievement.image.id. The URL points to the image as it was at the time the badge was issued, and follows this type of format: https://openbadgefactory.com/obv3/images/badge/{image_id}

The {image_id} is not the badge class ID or the issued badge ID; the complete image URL should be taken directly from credentialSubject.achievement.image.id.

For the generic badge class image (the visual defined in the badge itself, not linked to a specific issued badge), use the operations tagged “badge” in the API documentation: GET /v2/badge/{client_id}/image/{badge_id} returns one image and GET /v2/badge/{client_id}/image the images of all badge classes. Image data should be cached by the API client.

Public badge image URLs are also included in the response of GET /v2/badge/{client_id}; note that these URLs change whenever a badge image is updated.

Can I display OBF badges inside another platform?

Yes. A typical LMS, LXP or HR integration can retrieve information about an issued badge and display it in the learner or employee profile.

For the badge visual, use the image URL contained in the assertion JSON, credentialSubject.achievement.image.id, for example https://openbadgefactory.com/obv3/images/badge/{image_id}. The image represents the badge as it was at the time of issuing.

The external platform can then link the badge image to the public credential page, https://openbadgefactory.com/obv3/credentials/{assertion_id}. This allows the external platform to provide its own badge gallery or learner profile while Open Badge Factory remains the issuing and verification service.

PDF and downloadable formats

Can I retrieve the PDF version of an issued badge through the API?

No. Retrieving the PDF version of an issued badge is currently not supported in API v2.

Badge recipients can download their badges in PDF format when this option is enabled by the issuing organisation.

To give learners access to their credential from an external platform, link to the public credential page instead (see Can I retrieve the learner’s public badge page URL?).

Statuses

What do approved, accepted and unknown mean?

These values belong to different parts of the badge workflow and should not be interpreted as equivalent statuses.

• approved relates to a badge application;
• accepted relates to the reception of an issued badge;
• unknown is also a badge reception status. ‘Unknown’ is the same as ‘Not received’.

This distinction is particularly important when combining application data with badge issuing or recipient data.

How reception statuses appear in the API?

The API does not use the accepted / unknown terminology. Instead, the reception of an issued badge is described with boolean flags in the recipient data:

• received: the recipient has received (accepted) the badge;
• in_passport: the badge has been saved to Open Badge Passport;
• pdf_downloaded: the badge has been downloaded in PDF format.

A revoked badge has revoked set to true.

For example, a badge shown as Not received in reports has received set to false, and a badge shown as Accepted+pdf has both received and pdf_downloaded set to true.

Issued badge statuses

Badge applications have four statuses

Performance and rate limits

What is the API rate limit?

The API currently has a rate limit of approximately 10 requests per second per organisation. Requests beyond that are answered with HTTP status 429 Too Many Requests. The token endpoint has its own limit of one token request per 10 seconds.

Integrations should avoid unnecessary or redundant requests. If an application regularly reaches the rate limit, consider:

• using API filters where available;
• avoiding full-data synchronisation when only recent changes are required;
• caching data where appropriate;
• avoiding repeated requests for information that has not changed;
• reusing OAuth access tokens until they expire;
• reading lists with paging (limit and offset) instead of one request per item.

Badge resources and formats

Where can developers find the complete API specification?

This Knowledge Base article is intended to answer common questions, explain terminology and provide integration recommendations.

For the latest endpoints, request parameters, schemas and change log, developers should always refer to the technical API reference: OBF API v2 technical documentation.