Skip to main content

Getting Started with Open Credit

  1. Overview
  2. Register an App
  3. Get familiar with Open Credit
  4. Get familiar with authentication
  5. Request production access

Overview

Open Credit is a suite of RESTful web services developers can implement to build rich applications that send and receive credit using Credly.

In the documentation section, every publicly available endpoint is explained in detail. This page provides an introduction to building applications with Open Credit.

The current version of Open Credit has endpoints beneath the base path https://api.credly.com/v1.1. The version string, currently v1.1, is incremented with each minor release of Open Credit. When a new version of Open Credit is ready for release, we will officially notify all Open Credit developers by email to announce new features and reveal the timeline for deprecating older version(s) of Open Credit.

Register an app

To begin using Open Credit, first register an app in the My Apps section of the Credly developer portal. After filling out a short questionnaire, uploading an app icon, and agreeing to our terms of use, a Sandbox app will be visible on your dashboard.

Get familiar with Open Credit

With your new Sandbox app, you can use its API key and API secret to begin using Open Credit immediately. The API key and secret are passed with all requests as the headers X-Api-Key and X-Api-Secret. You can try out your app credentials on the command line:

curl \
 -H "X-Api-Key: <your API key>" \
 -H "X-Api-Secret: <your API secret>" \
 https://api.credly.com/v1.1/members

All API responses are JSON objects with the following structure:


{
  "meta": {
    "status_code": <int>,
    "status": <string>,
    "message": <string>,
    "more_info": <null|array>
  },
  "data": <mixed>
}

Every endpoint returning paginated array data, such as the "search members" example above, will include an additional property, "paging", as follows:


{
  "paging": {
    "page": <int>,
    "per_page": <int>,
    "order_direction": "ASC|DESC",
    "resources": {}
  }
}

The paging resources will typically contain "next" and "previous" values as fully qualified API calls; these can be used to traverse paginated data.

Get familiar with authentication

Open Credit provides a complete suite of endpoints for creating, updating, and managing user accounts. Many endpoints, such as those for sending credit, require an authenticated user to act on behalf of. Credly uses the HTTP basic authentication protocol for signing in users and receiving an access token.

To request an access token, send a POST request to /authenticate with a basic authentication header. For example:

curl \
 -H "X-Api-Key: <your API key>" \
 -H "X-Api-Secret: <your API secret>" \
 --user "<email address>:<password>" \
 --data "" \
 https://api.credly.com/v1.1/authenticate

If authentication succeeds, you will receive a response as follows:


{
  "meta": {
    "status_code": 200,
    "status": "OK",
    "message": "",
    "more_info": null
  },
  "data": {
    "token": "<access_token>",
    "refresh_token": "<refresh_token>"
  }
}

Access tokens are specific to your app and will expire three years after they're issued. For most use cases, you will only need to store the access token in your app's session for signing future requests. To sign requests with an access token, simply pass it as the access_token parameter. For example:

curl \
 -H "X-Api-Key: <your API key>" \
 -H "X-Api-Secret: <your API secret>" \
 "https://api.credly.com/v1.1/me?access_token=<your access token>"

If you need to persist user sessions longer than 3 years, instructions for renewing an access token using a refresh token is available in the User Management documentation.

Request production access

Sandbox applications are limited to 20 calls per user per minute and 20 unauthenticated calls per minute. Once you have built out the basic scaffolding of your application, you may request production access for your app using the My Apps dashboard for higher rate limits and full access to Open Credit.

See rate limiting documentation for more details.