Skip to content

Web Service API

This document describes the Credly web service API, a REST service that allows organizations to manage their badges and issue badges on behalf of other organizations.

API Conventions

  • All requests must use SSL.
  • Authentication is handled via HTTP Basic Authentication as described below.
  • All requests must be in JSON format with Content-Type: application/json
  • Clients of the web service must accept JSON as response data.
  • All references to static assets (e.g. image_url in Get Badges response and photo_url in List Organization responses) are subject to change. These resource locations can always be found by calling the appropriate API.

API Versions

  • 1.0 is the current version.

Backwards Compatibility

We won't introduce backwards-incompatible changes to a specific version of the API. If backwards-incompatible changes are necessary to support new features, then a new version of the API will be introduced. When a new version is introduced, both the new version and the prior version will be supported simultaneously. The prior version of the API will eventually be deprecated and removed.

Backwards- compatible changes include:

  • Adding a new attribute to an existing object is backwards-compatible.
  • Adding a new API path is backwards-compatible.

Backwards- incompatible changes include:

  • Changing or removing an existing path name is backwards-incompatible.
  • Changing or removing an existing object name is backwards-incompatible.
  • Changing or removing an existing attribute name is backwards-incompatible.

URL Construction

Web service URLs are constructed as follows:

Production Environment<endpoint_path>

Sandbox Environment

We recommend that you develop and test your integration against our sandbox environment before moving to production. URLs for requests to the sandbox environment are constructed as follows:<endpoint_path>


When you authenticate with an organization's Authorization Token, you only have access to that organization, its badge templates, and any badges it has issued.

Authentication is handled via HTTP Basic Authentication with the organization's authorization_token as the username and a blank password. Every request requires HTTP Basic Authentication.

Example headers for a POST request:

Accept: application/json
Authorization: Basic SFRkYXVTanFYeWVzNUxieExPNUdadzo=
Content-Type: application/json

Depending on what tool you're using to connect to the API, it may not be necessary to manually set any of these headers. For example, creating a badge template via the curl command line tool might look like this:

curl -u 'HTdauSjqXyes5LbxLO5GZw':''  \
  -X POST -H "Content-type: application/json" \
  -d '{"badge_template_id":"13034728-bb90-473b-ba8a-97b4fab04420",
       "recipient_email":""}' \

As this example demonstrates, the Authorization header is created by using the authorization_token as the HTTP username, with a blank password. For example, if the organization's authorization_token is HTdauSjqXyes5LbxLO5GZw, the Authorization header would be manually created like this:

  1. Create the standard username:password string with the authorization_token and a blank password: HTdauSjqXyes5LbxLO5GZw:.
  2. Base64 encode the username:password string: base64encode("HTdauSjqXyes5LbxLO5GZw:") = "SFRkYXVTanFYeWVzNUxieExPNUdadzo=".
  3. Create the complete Authorization header: Authorization: Basic SFRkYXVTanFYeWVzNUxieExPNUdadzo=.

Again, this process may be taken care of for your by whatever tool you are using, such as curl, a REST client library, etc.

The authorization_token grants full permission to the web service API on behalf of the organization, therefore the authorization_token should be treated with the same sensitivity as an admin password. Administrators can view their organization's authorization tokens within Organization Management under the Developers section.

OAuth2 Authentication

Credly supports authentication via OAuth2 Client Credentials grant. The first step in using OAuth authentication is to request that your Organization be configured to be configured to allow OAuth2 authentication. You will then be provided with your Client Id and Client Secret.

Production Environment OAUth Token Request URL

Sandbox Environment OAUth Token Request URL

Credly supports the following Scopes that must be requested when obtaining the OAuth 2 token:

  • issued_badges - For the Issued Badges Endpoint
  • badge_templates - For the Badge Templates Endpoint
  • recommendations - For the Recommendations Endpoint
  • workforce - For the Workforce Endpoint
  • Token request body example:

      "grant_type": "client_credentials",
      "scope": "desired scopes",
      "client_id": "client id for your application",
      "client_secret": "client secret for your application"

    Example authorization request headers:

    Accept: application/json
    Authorization: Bearer UC0RjBMkAQtKgWBNvjWWHiSoy1ax5tv0VgnwM2nw8KQ
    Content-Type: application/json

    Web Service Responses

    Request Result Status Code Response Body
    GET Success 200 (OK) The JSON resource
    GET Not found 404 (Not Found) { message: "Resource not found." }
    POST Success 201 (Created) The JSON resource with its URL in the Location header
    PUT Success 200 (OK) The JSON resource
    POST/PUT Missing required parameter 400 (Bad Request) { message: "Missing required parameter: email" }
    POST/PUT Validation failed 422 (Unprocessable Entity) { message: "Email address is invalid" }
    Any Unexpected error 500 (Internal Server Error) { message: "Oops. Something went wrong, but no details are available." }

    Wrapped Responses

    The web service wraps responses with the following format:

      data: {
        <response data>
      metadata: {
        <response metadata>

    Only certain responses contain <response metadata>. It's used for returning relevant info for paged results. In particular, Badge Templates and Issued Badges responses are paged and include <response metadata>. Refer to the documentation for those endpoints for details.

    Common Errors

    If you get the response...

    Response Then...
    { "message": "You need to sign in before continuing." } need to specify the correct Authorization header.
    { "message": "You have to confirm your account before continuing." } must confirm your account by responding to the confirmation email you received.
    { "message": "Your account is locked. Please contact us for assistance." } ...your account is locked.
    { "message": "Your account was not activated yet." } ...your account is disabled.

    Validation Failures

    The web service will validate data when creating and updating a resource. If validation fails, the server will return a 422 status code with a list of attributes that failed validation. The message value will contain a comma-separated list of validation errors, and an array of errors and their respective attribute names will also be included. For example:

      data: {
        "message": "Validation failed: Email can't be blank, ...",
        "errors": [
            "attribute": "email",
            "messages": [
              "can't be blank",