Making Authenticated API Calls

Summary

Ocelot API requests require both the API key and the Ocelot-specific digital signature. These values go into the HTTP headers x-api-key and x-ocelot-signature respectively.

Ocelot API responses and webhook events will contain the Ocelot-specific digital signature. These values go into the HTTP header x-ocelot-signature. The Ocelot API client may validate the signature. Our recommendation is to validate the signature on the client side.

Ocelot webhook event responses require the Ocelot-specific digital signature. These values go into the HTTP header x-ocelot-signature.

API Key

The API key must be included in the HTTP header x-api-key for API requests. The API key authenticates the Ocelot API client to the Ocelot API. The authentication then authorizes the client to use your chatbot.

It is generated in the service provider page in the Client Admin. For details on generation, see the guide Adding A Service Provider.

Following is an example of populating the x-api-key HTTP header when calling the Ocelot API to bulk register capabilities for your chatbot.

const request = {
    baseURL: baseUrl,
    method: 'POST',
    url: `/api/v1/chatbot/${chatbotId}/chatbot-service-provider/bulk/capability`,
    headers: {
        'x-api-key': apiKey,
    },
    data: {
        bulkOperationType: ChatbotServiceProviderCapabilityBulkOperationType.ReplaceAll,
        capabilities: capabilities,
    },
}

Digital Signature

Computing

For details, see the guide Computing Ocelot Digital Signature.

Signing

The computed digital signatures must be included in the HTTP header x-ocelot-signature for API requests and webhook event responses. These digital signatures authenticate the messages sent from the Ocelot API client to the Ocelot API.

The process is:

1. Compute the digital signature.
2. Add the computed value in the HTTP header x-ocelot-signature.

Verifying

Digital signatures will be in the HTTP header x-ocelot-signature for API responses and webhook events. These digital signatures authenticate the messages sent between the Ocelot API to the Ocelot API client.

The process is:

1. Compute the digital signature.
2. Read the value in the HTTP header x-ocelot-signature.
3. The verification passes only if the computed value and the HTTP header value are identical.