KB User's Guide - API - Accessing the Private API

This document explains how to obtain and API token and connect to the KB's Private API layer following the provisioning of your OAuth account.

Note: If you have not requested an OAuth account, please first review the information in KB User's Guide - API - Requesting an OAuth Account to submit a request.

Request an API Token

Once you have received your OAuth account information from the KB Team, you can use it to request an API token. To illustrate this process, we will use the application Postman, however, other similar applications may also be used.

  1. Create a new request. In Postman, this is done by clicking New > Request in the upper right-hand corner.

  2. Set the request method to POST and enter https://kb.wisc.edu/api/v1/oauth as the request URL.

  3. Under the Headers tab, add a new header with the "key" set to Content-Type and the "value" set to application/json.

  4. Under the Body tab, choose the raw option and enter format the request body as follows, replacing the username, client_id, password, and scope values with those that have been provided to you personally:

    {
    
        "username": "yourusername",
        "client_id": "yourusername_client",
        "grant_type": "password",
        "password": "yourpassword",
        "scope": "group:123;site:all;user:bbadger@wisc.edu"
    
    }
    

    Note: The entry for "client_id" will always be your username followed by _client, and the entry for "grant_type" should always be set to password.

  5. Click Send to send the request. The request response will appear in the lower half of the screen (if in Postman, be sure that you are in the Body tab) and will contain the following entries:

    • access_token
    • expires_in
    • token_type
    • scope
    • refresh_token

Making a Request to the Private API

Once you have obtained your API token, you can now pass this token in a GET request via the authorization header. If you were to make this request via Postman, it would be done as follows:

  1. Create a new request (New > Request)

  2. Set the request method to GET and enter the desired URL for the private API collection or entity you would like to access, e.g. https://kb.wisc.edu/demo/api/v1/private/articles, as the request URL.

    1. Note: If you are requesting data for an institution other than UW-Madison, make sure that you have replaced the domain (i.e. kb.wisc.edu) with your institution's KB domain and/or subsite directory. The subsite directory name should be the directory that corresponds to the group ID you entered for your account scope.

  3. Under the Authorization tab, set the "Type" to Bearer Token and paste your "access_token" into the "Token" field.

  4. Click Send to send the request. The request response will appear in the lower half of the screen and will contain the body of the collection or entity you requested.