Start building your own chatbot now!

SAP Conversational AI provides public APIs that can be consumed by bot developers to:

  • Configure their bots, with design time APIs
  • Interact with their bots, with run time APIs using a middleware

As of the October release, bot developers will be able to authenticate the API calls made by their middleware or clients to SAP Conversational AI using one of the following methods:

  • OAuth tokens (recommended method)
  • Bot (developer / request) tokens

Starting mid-2021, SAP Conversational AI will only support API calls that are accompanied with OAuth tokens, that’s why we strongly suggest you to migrate your chatbots to OAuth-based authentication now.

Depending on the token chosen, you are allowed to make different requests:

  • With your request token (version/environment), you can make requests in the RUNTIME API, to analyze text or start a conversation. When you create a new bot, by default, your bot has only one main version v1 and is assigned to the “DEVELOPMENT” environment. You will have one request token for each version and for each environment of your bot.
  • With your developer token, you can make requests on every endpoint our API provides.

In this tutorial, we will walk you through the steps for calling SAP Conversational AI APIs using OAuth tokens:

Option 1: Generating OAuth token using Client Credentials

  • Step 1: Generate OAuth client for design time/run time APIs
  • Step 2: Generate OAuth token using Client Credentials
  • Step 3: Call SAP Conversational AI APIs using OAuth token

Option 2: Generate OAuth Token using Client Certificate

  • Step 1: Generate OAuth client for design time/run time APIs
  • Step 2: Generate OAuth token using Client Certificate
  • Step 3: Call SAP Conversational AI APIs using OAuth token

Why you should migrate your chatbots to oAuth instead of using Bot tokens

The following table shows the differences between OAuth and Bot tokens and the advantages of using OAuth tokens:

OAuth tokenDeveloper / Request token
Token automatically expires after twelve hours and needs to be regenerated every twelve hoursToken once generated remains the same throughout the lifetime of a bot and regeneration of the token has to be triggered manually
More secureLess secure
Need to regenerate new token every 12 hoursMust update token in middleware every time a new token is generated
No need to update credentials in the middleware every time a new token is generatedNeed to update token in middleware every time regeneration happens
Certificate based token generation is useful for server to server communicationNo certificate-based token generation possible

Difference between APIs and authentication

SAP Conversational AI provides two types of APIs:

Design-timeRun-time
APIs used to configure the bot (e.g. /entities, /intents, /dataset...)APIs used to interact with the bot (e.g. /dialog or /request...)
Works with developer token of the botWorks with request, version or environment token of the bot

How to migrate your chatbots using OAuth token

You can either follow the steps in the video or described below:

Option 1: Generating OAuth token using Client Credentials

Step 1: Generate OAuth client for design time/run time APIs

Go to your Bot Settings and click Tokens.

Click the Generate button under the Run time APIs or Design time APIs.

Choose Client Credentials and click Next.

Once the client is generated, the following fields are displayed:

FieldUsage for Token Generation
Auth URLURL to be used for generation of OAuth token
Client IDIdentifier of the OAuth client, to be passed in client_id field in request body
Client secretSecret for OAuth Client to be passed in client_secret field in request body

Step 2: Generate OAuth token using Client Credentials

curl -X POST <Auth_URL> -d ‘grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>’

Note: OAuth tokens expire after twelve hours. The value for expires_in field indicates the time (in seconds).

Step 3: Call SAP Conversational AI APIs using OAuth token

Design time APIs
Headers:

  • Authorization: Bearer <Designtime_OAuth_Token>
  • X-Token: Token <Developer_Token>

Run time APIs
Headers:

  • Authorization: Bearer <Runtime_OAuth_Token>
  • X-Token: Token <Request_Token>

Option 2: Generating OAuth token using Client Certificate

Step 1: Generate OAuth client for design time/run time APIs

Go to your Bot Settings and click Tokens.

Click the Generate button under the Run time APIs or Design time APIs.

Choose Client Certificate and click Next.

Paste the certificate code in the text box and click Generate.

Once the client is generated, the following fields are displayed:

FieldUsage for Token Generation
Auth URLURL to generate OAuth token
Client IDIdentifier of the OAuth client to be passed in client_id field in request body

Step 2: Generate OAuth Token using Client Certificate

curl –cert cert.pem –key key.pem -X POST <Auth_URL> -d ‘grant_type=client_x509&client_id=<client_id>’

Here cert.pem is the public key certificate and key.pem is the private key of the certificate.

Note: OAuth tokens expire after twelve hours. The value for expires_in field indicates the time (in seconds).

Step 3: Call SAP Conversational AI APIs using OAuth Token

To call an API, you need to paste the token in the Headers of the API call.

Design time APIs
Headers:

  • Authorization: Bearer <Designtime_OAuth_Token>
  • X-Token: Token <Developer_Token>

Run time APIs
Headers:

  • Authorization: Bearer <Runtime_OAuth_Token>
  • X-Token: Token <Request_Token>

 

Note: If you don’t need the OAuth token anymore, it is recommended that you delete the token to avoid any security issues.

Congrats, you know how to generate OAuth tokens using Client Credentials and Client Certificate, allowing you to integrate various middleware with your chatbots to interact in a secure and robust manner.

Ask your questions on SAP Answers or get started with SAP Conversational AI!

Follow us on