Authorization Tokens

Overview

The Credly platform allows organizations to use Authorization tokens to access the Credly system. These can be created via the API directly, or through the Credly UI. Authorization tokens can be used alongside, or in place of, OAuth 2.0.

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

GET /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 /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 /organizations/<organization_id>/authorization_tokens/rotate

Optional body parameter to include a new description

If description is not provided the previous description will be used. 

{
  "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": {}

}

Accessing the Credly API

After generating an Authorization token, you can use it to access the Credly API. Authentication is handled via HTTP Basic Authentication with the organization's `authorization_token` as the username and a blank password.

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:

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