OAuth

Overview

The Credly platform allows organizations to use OAuth 2.0 to access the Credly system. This is done through the client_credentials grant type, which allows your application to access the Credly API. OAuth 2.0 can be used alongside, or in place of, our existing authorization token system. You can manage your OAuth applications via API or through the Credly web application by navigating to "Developers > OAuth Applications".

Retrieving OAuth Applications

You can retrieve a list of all OAuth applications your organization has by making a request to the following endpoint.

Request

GET /organizations/<organization_id>/oauth_applications

Response

200 OK

{
  "data": [
    {
      "id": 42,
      "name": "My Custom OAuth Application",
      "description": "This OAuth application is used by our development team to handle our integrations.",
      "created_at": "2025-04-15T21:21:10.440Z",
      "updated_at": "2025-04-17T14:18:05.740Z",
      "last_used_at": null,
      "last_successfully_used_at": null,
      "uid": "C-qqxBybJxkrpX5VO5GkDtXbF9wcXZHFS-TfjHvPpP8",
      "created_by_id": "783148c8-213f-4291-896f-aa9328fc7ee5",
      "created_by_type": "User",
      "created_by_name": "John Doe",
      "creator_available": true,
      "secret": null
    },
    {
      "id": 46,
      "name": "Second OAuth Application",
      "description": "This application is used by our HR team.",
      "created_at": "2025-04-17T15:03:59.865Z",
      "updated_at": "2025-04-17T15:07:42.156Z",
      "last_used_at": null,
      "last_successfully_used_at": null,
      "uid": "BAyJYWZE6zK02WF15QXcmaiwNTkvAIFQlk9X42QbLNw",
      "created_by_id": "783148c8-213f-4291-896f-aa9328fc7ee5",
      "created_by_type": "User",
      "created_by_name": "John Doe",
      "creator_available": true,
      "secret": null
    }
  ],
  "metadata": {
    "count": 2,
    "current_page": 1,
    "total_count": 2,
    "total_pages": 1,
    "per": 50,
    "previous_page_url": null,
    "next_page_url": null
  }
}

Retrieving a single OAuth Application

You can retrieve a single OAuth application by making a request to the following endpoint.

Request

GET /organizations/<organization_id>/oauth_applications/<oauth_application_id>

Response

200 OK

{
  "data": {
    "id": 42,
    "name": "My Custom OAuth Application",
    "description": "This OAuth application is used by our development team to handle our integrations.",
    "created_at": "2025-04-15T21:21:10.440Z",
    "updated_at": "2025-04-17T14:18:05.740Z",
    "last_used_at": null,
    "last_successfully_used_at": null,
    "uid": "C-qqxBybJxkrpX5VO5GkDtXbF9wcXZHFS-TfjHvPpP8",
    "created_by_id": "783148c8-213f-4291-896f-aa9328fc7ee5",
    "created_by_type": "User",
    "created_by_name": "John Doe",
    "creator_available": true,
    "secret": null
  },
  "metadata": {
  }
}

Creating an OAuth Application

An OAuth Application is required to generate access tokens. You can either create an application in the platform, or via the API. The uid key and the secret key are the Client ID and Client Secret that you will need in order to obtain access tokens.

Reminder that this is the only time you will get to see the client secret.

Request

POST /organizations/<organization_id>/oauth_applications

Parameters

Name	Description
name	Required. The name of your application.
description	Optional. A description of your application.

Response

201 Created

{
  "data": {
    "id": 42,
    "name": "My Custom OAuth Application",
    "description": "This OAuth application is used by our development team to handle our integrations.",
    "created_at": "2025-04-15T21:21:10.440Z",
    "updated_at": "2025-04-17T14:18:05.740Z",
    "last_used_at": null,
    "last_successfully_used_at": null,
    "uid": "C-qqxBybJxkrpX5VO5GkDtXbF9wcXZHFS-TfjHvPpP8",
    "created_by_id": "783148c8-213f-4291-896f-aa9328fc7ee5",
    "created_by_type": "User",
    "created_by_name": "John Doe",
    "creator_available": true,
    "secret": "KGatTudJ8BpijZNn-qX6YM7TP5WnK3YrGrur0DdN_8E"
  },
  "metadata": {
  }
}

Updating an OAuth Application

Request

PUT /organizations/<organization_id>/oauth_applications/<oauth_application_id>

Parameters

Name	Description
name	Optional. The new name of your application.
description	Optional. A new description of your application.

Response

200 OK

{
  "data": {
    "id": 42,
    "name": "Updated OAuth Application (with a new name!)",
    "description": "This OAuth application is used by our development team to handle our integrations.",
    "created_at": "2025-04-15T21:21:10.440Z",
    "updated_at": "2025-04-17T14:18:05.740Z",
    "last_used_at": null,
    "last_successfully_used_at": null,
    "uid": "C-qqxBybJxkrpX5VO5GkDtXbF9wcXZHFS-TfjHvPpP8",
    "created_by_id": "783148c8-213f-4291-896f-aa9328fc7ee5",
    "created_by_type": "User",
    "created_by_name": "John Doe",
    "creator_available": true,
    "secret": null
  },
  "metadata": {
  }
}

Deleting an OAuth Application

Request

DELETE /organizations/<organization_id>/oauth_applications/<oauth_application_id>

Response

204 No Content

OAuth Scopes

Credly supports the following OAuth scopes. Any combination of these can be requested when generating an access token.

Name	Description
authorization_tokens	Read, write, and delete authorization tokens.
badge_templates	Read, write, and delete badge templates
events	Read webhook events relevant to your organization
invitations	Read, invite, and delete users to your organization
issued_badges	Read, issue, replace, revoke, and delete issued badges
memberships	Read, write, and delete your organization's memberships
oauth_applications	Read, write, and delete OAuth Applications
pathways	Read, write, and delete pathways
recommendations	Read, write, and delete recommendations
workforce	Read, write, and delete employee records

Generating Access Tokens

Request

Once you have the client ID and client secret, you can generate an access token by making a request to the following endpoint. Note that this endpoint does not use the api.credly.com domain, but instead uses www.credly.com.

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

Parameters

Name	Description
client_id	Required. This is the Client ID you got when you registered your application, above.
client_secret	Required. This is the Client Secret you got when you registered your application, above.
grant_type	Required. Must be the string `client_credentials`.
scope	Required. A space-separated list of scopes. See OAuth Scopes for more information

Response

A successful request will return a JSON response including the access token:

{
  "access_token": "IpsPAjhpm1RjCx30ggTpx2xXmHKUpmZcQbcKkecpxWs",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "issued_badges",
  "created_at": 1739996399
}

Accessing the Credly API

After obtaining an access token from the endpoint above, you can use it to access the Credly API. To do this, include the access token in the Authorization header of your request, along with the Bearer prefix.

GET `/organizations/<organization_id>/badges`
Authorization: Bearer [access token]