Creating and using API keys

Follow these steps to use an API key in a REST API call.

Prerequisites: Before performing this task, you should have performed the steps in Making your first REST API call to understand how to make a simple call. If you want to skip that quickstart, you should at least have a Bold360 AI account and knowledge base and know the basics about forming REST URLs.

About this task: This procedure shows how to call a Bold360 AI REST API endpoint that requires an API key in order to perform a simple article search.

API keys are identifiers that can be used when accessing Bold360 AI services. An account can have multiple API keys, and you can specify read/write permissions, knowledge base access, IP addresses, and HTTP referer domains allowed for each key.

Steps:

  1. In the Bold360 AI Console, select your knowledge base and go to Admin Center > API Keys. Click + Add API Key.
  2. Type a descriptive name for the key and select the permissions and knowledge bases the key should be allowed to access. For this example, be sure to grant at least Read access to the Knowledge Base permission and allow read access to the knowledge base you are using. Click Save to create the key.

    Important: If you want users of this API key to be able to perform write actions, you must also restrict access based on IP addresses and/or HTTP referer.

    For more information about creating API keys, see the How to create an API key? topic on the Bold360 AI support center.

  3. Open the Bold360 AI REST API Reference in a separate tab or window. Navigate to the "Sessionless Simple Search" /api/kb/v1/simpleSearch endpoint.

    Tip: Another search endpoint, /api/kb/v1/search, requires a session ID instead of an API key.

  4. In a text editor or other tool that you use to assemble REST URLs, paste the /api/kb/v1/simpleSearch endpoint after the server portion of your URL. For example: https://account_name.nanorep.co/api/kb/v1/simpleSearch.
  5. Notice in the reference documentation that the simpleSearch endpoint requires the kb, query, apiKey, and referer parameters.
    1. Add the kb parameter to your URL and specify the name or ID of your knowledge base. For example: https://account_name.nanorep.co/api/kb/v1/simpleSearch?kb=my_kb.
    2. Add a query parameter to your URL that will match the title (or phrasing or synonyms) of one or more articles in your KB. For example: https://account_name.nanorep.co/api/kb/v1/simpleSearch?kb=my_kb&query=test.
  6. Try pasting this URL into the browser without specifying the API key. In the Network tab, you should see an HTTP 403 error. Open the Developer Tools to see details.



  7. Copy the API key Bold360 AI Console and use it to specify the apiKey parameter in your URL. For example: https://account_name.nanorep.co/api/kb/v1/simpleSearch?kb=my_kb&query=test&apiKey=c72ee13f-e16d-43cb-9914-70acb943be34.



  8. You should see articles returned successfully in JSONP format. In the Network tab of the Developer Tools, you can examine or copy the JSONP response.



  9. Notice that the reference documentation says that the referer parameter is required, but you did not need to specify it in the URL. This is because most browsers pass HTTP referer information in a message header automatically.

    Note: If you are sending REST API endpoint through some mechanism other than a web browser, you may need to specify several HTTP headers when sending requests to the server.

  10. When using API keys in your websites and applications, see Security issues and best practices.
What next? Try other parameters supported by the /api/kb/v1/simpleSearch endpoint. For example:
  • precision: Set this parameter to fullResults, loose, normal, restrictive, or veryRestrictive to see a different set of results based on how well your query matches article titles.
  • maxResults: Set this parameter to the maximum number of matches to return.
  • labelId: Set this parameter to limit the results to articles that have been tagged with a specific label. Specify this ID as a hex value.