Skip to main content

Best Practices

  1. Caching Open Credit data
  2. Account verification
  3. Images
  4. Rich Text Formatting
  5. Managing Organization accounts
  6. Rate limiting

Caching Open Credit data

When building an app with Open Credit, it is important to evaluate which data can be safely cached to avoid multiple calls and which data will change too often to be cached.

Although the use case and needs of your app may vary, here are some best practices:

Access tokens and refresh tokens will not change under typical usage while a user is using your app. These data can be cached within a session or even longer.

Profile data for a logged-in user may change under typical usage. Although you may cache profile data for a logged-in user, we recommend a short cache lifetime due to the many ways a user's profile data can be updated or modified by external actions.

Badge data is considered ephemeral and should not be cached.

Accepted member badges can be cached within a session. Please note that it is possible for members to delete member badges after they have been accepted via any app or the Credly website.

For most other scenarios, we recommend using fresh data from Open Credit rather than caching data returned from the API for optimal consistency and correctness of data. Open Credit is designed from the ground up to scale with the needs of the applications our users build.

Account verification

Open Credit requires all members to verify their email addresses before they can use them to give or receive credit. Due to this restriction, app developers implementing a user registration workflow should note that before a new account can give a badge or accept a badge, the new user must click the verification link sent to the email address they registered with and complete the registration flow on credly.com. The same is true for additional email addresses added after account creation. For an ideal experience, you should push users toward the external email verification workflow after they create an account.

The one exception to the aforementioned account verification workflow are Partner and Enterprise level apps. Apps at these levels have the option to create and verify user accounts without requiring users to click a verification link and without notifying the user in in any other way upon account creation. If you are a Credly Partner or Enterprise level user, contact your support manager for guidance on automatically verifying user accounts you create.

Images

As part of the rich visual experience within digital credential systems powered by Open Credit, images can be uploaded in several places throughout Open Credit. For ease of implementation, all endpoints accepting file uploads will accept either multipart form data or a base64 encoded string. Uploaded images are stored on Open Credit's CDN powered by Amazon S3.

To optimize bandwidth usage, most uploaded images are made available in multiple sizes according to a defined set of size codes, which are string suffixes that can be appended to filenames to request a specific image size. For example, an image with the filename filename.png with the size code _1 can be requested with the filename filename_1.png to return a specific size. As a quick reference, the complete set of size codes for badges and member avatars is below.

Image Type Size Code Dimensions

Member Avatars _1 28×28
_3 40×40
_5 55×55
_7 60×60
_9 70×70
_11 80×80
_13 120×120
_15 138×138
_17 140×140
_19 170×170

Badge Images _1 36×36
_3 55×55
_5 72×72
_7 90×90
_9 100×100
_11 120×120
_13 180×180
_15 280×280
_17 600×600


Rich Text Formatting

When creating a badge on Credly.com, users may choose to use a limited set of rich text options to format the data they input for the following fields: description, criteria, and evidence prompt. (No other fields support HTML formatted text.) Only the following HTML tags are supported: b, i, ul, li, p, br, a (for "a", only the "href" attribute is allowed).

When retrieving badge data via the Open Credit API, by default the API will not return any HTML-formatted data, even if it is exists for the supported field. Open Credit proactively strips all HTML tags returned by the API to ensure that only those integrations that specifically desire and are expecting to accommodate formatted text will receive it.

We designed HTML support to be reactive to the header X-Allow-Html: 1 which is off by default. When X-Allow-Html is not set or is set to "0", Open Credit will strip all tags without prejudice before returning any string output. Therefore, only those API calls which specifically set a header X-Allow-Html: 1 will retrieve formatted text. So if you do not wish to retrieve HTML, simply do not set the header.

When posting data via the Open Credit API for the badge description, criteria and evidence prompt fields, you may include the supported tags only. An HTML purifier that runs on the Open Credit API will reject illegal tags or attributes. The API will also close unclosed tags in the event that the maximum length for the field is exceeded at input time.

Managing Organization accounts

Open Credit supports two types of member accounts: users and organizations. Organizations can be added during account creation using the is_organization request parameter as demonstrated in the User Management documentation. When you create an account this way, two Credly members will be created: a "user" who logs in with an email address and password and an "organization" managed by the user. The underlying implementation of organization and user accounts uses an abstract principle of "member management" which will be expanded upon in future versions of Open Credit. The current default behavior of member management is to act on behalf of the "managed" organization when a user with an organization makes an authenticated request. To override this default behavior and act on behalf of the user instead of the organization, you may pass the behalf_of parameter, set to the ID of any member the authenticated user has permission to manage. For more information, please see User Management documentation.

Rate limiting

All apps using Open Credit are subject to rate limiting. A Sandbox app may make 20 unauthenticated requests per minute (requests not on behalf of a particular user), and 20 authenticated requests per minute per user. For any app intended to be used in production, please request production access to gain access to higher rate limits.

Open Credit currently provides the following rate limiting tiers based on your anticipated usage:

Tier Unauthenticated calls per minute Authenticated calls per user per minute
Sandbox 20 20
Light 120 120
Medium 240 240
Heavy 480 480
Enterprise No limit No limit

Most apps granted production access will be created within the Light usage tier. If your requests are being throttled because you exceeded the rate limiting threshold, please contact us and we will elevate your access level. Enterprise apps are not subject to rate limiting.

When a request is throttled, you will receive the following response from the API:


{
    "meta": {
        "status_code": 401,
        "status": "REQUEST_LIMIT_EXCEEDED",
        "message": "Too many requests for this app",
        "more_info": null
    },
    "data": null
}