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:

Create the standard username:password string with the authorization_token and a blank password: HTdauSjqXyes5LbxLO5GZw:.
Base64 encode the username:password string: base64encode("HTdauSjqXyes5LbxLO5GZw:") = "SFRkYXVTanFYeWVzNUxieExPNUdadzo=".
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.

Retrieving Authorization Tokens

Authorization token information can be obtained via an API call. Note that if you use an authentication token that does not have write or delete permissions, the list of returned authentication tokens will be truncated to show only the read-only tokens.

Request

POST v1/organizations/<organization_id>/authorization_tokens

Response

{
  "data": [
    {
      "id": "eec89e5a-d9fa-44f4-ae71-22fad2e58d8c",
      "token": "RnsDbkhD31hw7u2WnNymVEDgn3k123443H1w3",
      "owner_id": "88cf96b7-e4ca-4a17-b938-a72bf2b9c273",
      "description": "A new token for use",
      "write_enabled": true,
      "read_enabled": true,
      "delete_enabled": true,
      "created_at": "2020-05-28T16:44:41.034Z",
      "expires_at": "2025-01-14T20:54:48.303Z",
      "owner": {
        "type": "Organization",
        "id": "88cf96b7-e4ca-4a17-b938-a72bf2b9c273",
        "name": "Acclaim",
        "url": "https://www.credly.com/api/v1/organizations/88cf96b7-e4ca-4a17-b938-a72bf2b9c273"
      }
    },
    {
      "id": "11ec08c1-acc4-46ce-a111-df3d8f92f092",
      "token": "dSPftsJqS9KiwueFdfhXalfYGsB0HEgGAdkM",
      "owner_id": "88cf96b7-e4ca-4a17-b938-a72bf2b9c273",
      "description": "A token to be used for external integrations.",
      "write_enabled": true,
      "read_enabled": true,
      "delete_enabled": true,
      "created_at": "2020-06-03T22:43:10.192Z",
      "expires_at": "2024-12-25T17:21:29.841Z",
      "owner": {
        "type": "Organization",
        "id": "88cf96b7-e4ca-4a17-b938-a72bf2b9c273",
        "name": "Acclaim",
        "url": "https://www.credly.com/api/v1/organizations/88cf96b7-e4ca-4a17-b938-a72bf2b9c273"
      }
    }
  ],
  "metadata": {
    "count": 2,
    "current_page": 1,
    "total_count": 2,
    "total_pages": 1,
    "per": 50,
    "previous_page_url": null,
    "next_page_url": null
  }

}

Creating Authorization Tokens via API

New authorization tokens may be created by using an existing token with write permissions. This has no affect on the token used to perform the request. The new token will have a default expiration of 180 days.

Request

POST v1/organizations/<organization_id>/authorization_tokens

Optional body parameter to include a new description

{
  "description": "rotating the token in 2024"
}

Response

{
  "data": {
    "id": "eec89e5a-d9fa-44f4-ae71-22fad2e58d8c",
    "token": "{NEWLY GENERATED AUTHORIZATION TOKEN}",
    "owner_id": "88cf96b7-e4ca-4a17-b938-a72bf2b9c273",
    "description": "rotating the token in 2024",
    "write_enabled": true,
    "read_enabled": true,
    "delete_enabled": true,
    "created_at": "2020-05-28T16:44:41.034Z",
    "expires_at": "2025-01-14T16:06:53.658Z",
    "owner": {
      "type": "Organization",
      "id": "88cf96b7-e4ca-4a17-b938-a72bf2b9c273",
      "name": "Acclaim",
      "url":
        "https://www.credly.com/api/v1/organizations/88cf96b7-e4ca-4a17-b938-a72bf2b9c273"
    }
  },
  "metadata": {}

}

Rotating Authorization Tokens via API

Authorization tokens are set to expire after a default of 180 days. To facilitate the rotation of authorization tokens, the Credly API allows tokens to be rotated via POST call. Upon rotating the authorization token, a new token will be generated and returned and the token used to ake the request will immediately be unavailable for use.

Request

POST v1/organizations/<organization_id>/authorization_tokens/rotate

Optional body parameter to include a new description

{
  "description": "rotating the token in 2024"
}

Response

{
  "data": {
    "id": "eec89e5a-d9fa-44f4-ae71-22fad2e58d8c",
    "token": "{NEWLY GENERATED AUTHORIZATION TOKEN}",
    "owner_id": "88cf96b7-e4ca-4a17-b938-a72bf2b9c273",
    "description": "rotating the token in 2024",
    "write_enabled": true,
    "read_enabled": true,
    "delete_enabled": true,
    "created_at": "2020-05-28T16:44:41.034Z",
    "expires_at": "2025-01-14T16:06:53.658Z",
    "owner": {
      "type": "Organization",
      "id": "88cf96b7-e4ca-4a17-b938-a72bf2b9c273",
      "name": "Acclaim",
      "url":
        "https://www.credly.com/api/v1/organizations/88cf96b7-e4ca-4a17-b938-a72bf2b9c273"
    }
  },
  "metadata": {}

}

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

https://www.credly.com/oauth/token

Sandbox Environment OAUth Token Request URL

https://sandbox.credly.com/oauth/token

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." }`	...you need to specify the correct Authorization header.
`{ "message": "You have to confirm your account before continuing." }`	...you 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",
          ...
        ]
      },
      ...
    ]
  }
}