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