Provision an API key for GES
Contents
Use the Environment Service API to assign API keys to a specific contact center and to validate that API keys were successfully assigned to the correct contact center.
If you plan to work with the Genesys Engagement Service (GES) APIs, then you must first provision an API key. An API key is a unique identifier for an application within a specific contact center. Genesys uses your GES API key to associate a Callback API request with your tenant. If an API key has not been provisioned for GES, then you cannot use the GES APIs. On the other hand, if you use basic in-queue callbacks only, you do not need to provision the API key.
The contact center-to-API key relationship is one-to-many. That is, one contact center can have many API keys assigned to it. An API key can be assigned to only one contact center.
To provision an API key for GES, you use the Environment Service API in the gauth namespace. For information about Genesys Authentication, see About Genesys Authentication.
All operations supported by the Environment Service API require authenticated access. You'll need client credentials and an authentication token to add an API key to the Environment Service. The token is sent with the request to the Environment Service to store the API key. For information, see Create an authentication token.
What you'll need to do to provision an API key
To provision an API key for GES, you'll do the following:
- Create an API key.
The API key must be unique. You decide what you want to use for a key, but Genesys recommends that you generate a UUIDv4 and use that as your API key for GES. - Find the contact center ID (CCID) for the contact center to which you'll assign the API key.
- Assign the API key to the contact center.
- Validate the API key. You can use a GET request to check that the API key is assigned to the correct CCID. You can also use the Callback UI to validate the API key.
If you need to remove an API key from a CCID, see Unassign an API key.
For more information about using the Environment Service API, including how to change CORS settings, or information about Callback APIs, see Additional resources.
Get the appropriate contact center ID
GET env:8091/environment/v3/contact-centersThe API responds with the CCID, Environment ID, domain, and authentication information.
If you don't have a CCID already assigned to the appropriate contact center, see Add a contact center.
Assigning an API key to a contact center
You create your own API key. Use an API key that is random and unique. The assignment of an API key fails if the API key already exists or is assigned to another contact center. Genesys recommends that you generate a UUIDv4 and use that as your API key.
Remember that all operations supported by the Environment Service API require authenticated access. You'll need client credentials and an authentication token to assign the API key to a contact center. The token is sent with the request to the Environment Service to store the API key. For information, see Create an authentication token.
To provision and associate an API key with your contact center, use the following POST request:
POST .../environment/v3/contact-centers/{ccid}/api-keysInclude the API key attribute (apiKey) in the body of the POST API request. For example:
curl --location --request POST 'env:8091/environment/v3/contact-centers/ed4c03f3-6275-4419-8b2b-11d14af10655/api-keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer f3aa2109-8889-4182-b2b7-d86917c53e4e' \
--data-raw '{
"data": {
"apiKey" : "78fd8f03-d9d0-4140-8aae-09f3f15d1392"
}
}'After you've assigned the API key to the contact center, the key is used as the value for x-api-key in the header of every request to the GES APIs.
Validating that the API key is correctly assigned to a contact center
To verify that the API key for GES was successfully assigned to the contact center where GES is deployed, use the API key that you created for GES to look up the CCID. You can also use the CCID to retrieve the collection of API keys assigned to the contact center; ensure the API key for GES is included.
To find the contact center to which a specific API key is assigned, use the following GET request. The API key must be URL-encoded. For information, see Google URL-Encoding.
GET .../environment/v3/contact-centers/api-key/<url-encoded api key value>The API response provides the CCID, Environment ID, domain, and authentication information.
To retrieve the list of API keys assigned to a contact center, use the following GET request:
GET .../environment/v3/contact-centers/{ccid}/api-keysThe API returns the list of API keys assigned to the CCID.
Validating an API key using the Callback UI
For information about validating an API key using the Callback UI, see Validating your API key in the Callback Administrator's Guide.
Unassigning an API key
To remove an API key from a contact center, use the following DELETE operation, where {apiKey} is the API key you want to remove from the contact center:
DELETE .../environment/v3/contact-centers/{ccid}/api-keys/{apiKey}Additional resources
When provisioning an API key for GES or working with GES APIs, you might find the following resources helpful:
- For detailed information about using the Genesys Authentication Environment Service API to create authentication tokens or to add a Genesys tenant, contact center, or data center, see Provision Genesys Authentication.
- The documentation for GES REST APIs is available through the Genesys Multicloud CX Developer Center. The GES/Callback APIs are:
- Callbacks — Create, retrieve, cancel callbacks.
- Estimated Wait Time —Retrieve Estimated Wait Time.
- Availability — Retrieve time slots for a callback, matching Office Hours.
- Call In — Request the phone number to call in.
- Queue Status — Retrieve information about a queue's readiness to accept callbacks.
- Statistics — Provides a proxy to the GWS Statistics API. To use the Callback Statistics API, you must first register your GWS credentials in the Callback UI (Developer > Credential Management > GWS Credentials tab).
- For web-based callbacks, you might need to configure or update CORS domains. For information, see Update CORS settings.