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

https://api.credly.com/v1/<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:

https://sandbox-api.credly.com/v1/<endpoint_path>

Authentication

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",
       "issued_at":"2019-03-22T00:00:00-04:00",
       "issued_to_first_name":"test",
       "issued_to_last_name":"bunny",
       "recipient_email":"user@example.com"}' \
  https://api.credly.com/v1/organizations/08bcedcd-3f67-40e9-b857-1ed8e0a80d6d/badges

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

http://api.credly.com/oauth/token

Sandbox Environment OAUth Token Request URL

http://sandbox-api.credly.com/oauth/token

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

Example authorization request headers:

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

Web Service Responses

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...

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",
          ...
        ]
      },
      ...
    ]
  }
}