Provision API keys

Learn how to provision API keys for Digital Channels.

Related documentation:

• How Digital Channels works
• Suite-level guide
• All services
• Digital Channels Release Notes

RSS:

• For private edition

Important

“Nexus” is the simplified name we use for the Digital Channels application and nodes, so you’ll see that name referenced throughout this document.

Complete the steps on this page to provision API keys for Digital Channels.

Prerequisites

Review the Prerequisites table and make sure you have all the listed information before you get started. The values in this table are referenced later by the name in the Variable column.

Prerequisites

Parameter	Variable	Type	Example	Notes
Auth URL	$authURL	HTTPS URL string	https://auth.mydomain.com	Host of the Auth Services load balancer.
Contact Center ID	$ccId	string	578ec98e-f07c-46ad-9675-f36c22f3ba9f	The contact center ID provisioned in Web Services and Applications. If you don't have this ID, see Get contact center ID from GWS below.
GWS admin username	$gwsAdminName	string	ops	The GWS ops credentials. See Provision Genesys Web Services and Applications.
GWS admin password	$gwsAdminPass	string	ops	The GWS ops credentials. See Provision Genesys Web Services and Applications.
Digital Channels FQDN URL	$nexusURL	HTTPS URL string	https://nexus.mydomain.com	The fully qualified domain name (FQDN) for Digital Channels.
Tenant Name	$tenantName	string	premise_tenant	The tenant name you used as <$tenantName/$ccId> in the Enable Nexus UX step.
Tenant User	$tenantUser	string	nexus	The Person username from your tenant configuration. See Create a Person object.
Tenant User Password	$tenantUserPassword	string	nexus_password	The Person password from your tenant configuration. See Create a Person object.

Tenant API keys

Important

Use a REST client or curl utility to make the requests explained on this page. Make sure to substitute the variables - prefixed with '$' - with their values.

Each API key you provision has a tenant or a set of tenants to which it is provisioned. The API key is also associated with a set of permissions. In the example below, we create a tenant API key with consumer chat API key permissions. Complete the steps below to provision an API key. First, get the authentication token by sending a POST request to GWS:

curl --user nexus_client:<client secret token> --request POST '$authURL/auth/v3/oauth/token' \  
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=$ccId\\$tenantUser' \
--data-urlencode 'client_id=nexus_client' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'password=$tenantUserPassword'

The expected response:

{"access_token":"<$outGWSAccessToken>","token_type":"bearer","refresh_token":"<refresh_token>","expires_in":43199,"scope":"*"}

As an output of this step, you will have the GWS access token for the tenant:

Parameter	Variable	Type	Example	Notes
Tenant GWS access token	$outGWSAccessToken	UUID string	9b7682b7-cbce-422f-9bbb-ecda85e61695	The access_token from the response example.

To provision the API key, send a POST request to Digital Channels:

curl --request POST '$nexusURL/nexus/v3/apikeys' \
--header 'Authorization: $outGWSAccessToken' \
--header 'Content-Type: application/json' \
--data '{
    "enabled": true,
    "tenant": "$ccId",
    "name": "API key for $tenantName",
    "permissions": [
        "nexus:consumer:chat"
    ]
}'

The expected response:

{
    "id": "<Your new created API key>",
    "tenant": "$ccId",
    "name": "API key for $tenantName",
    "permissions": [
        "nexus:consumer:chat"
    ],
    "enabled": true,
    "created": "<Date and time of creation>",
    "revoked": false,
    "expires": false,
    "createdby": "<User who created this API key>",
    "capacity": 120,
    "frequency": 60
}

As an output of this step, you will have the tenant API key:

Parameter	Variable	Type	Example	Notes
Tenant API Key	$apikey	UUID string	9b7682b7-cbce-422f-9bbb-ecda85e61695	The <Your new created API key> from the response example

Cluster API keys

Complete the following steps to provision a cluster (multi-tenant) API key.

First, get the cluster authentication token by sending a POST request to GWS:

curl --user nexus_client:<client secret token> --request POST '$authURL/auth/v3/oauth/token' \  
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=$gwsAdminName' \
--data-urlencode 'client_id=nexus_client' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'password=$gwsAdminPass'

The expected response:

{"access_token":"<$outClusterGWSAccessToken>","token_type":"bearer","refresh_token":"<refresh_token>","expires_in":43199,"scope":"*"}

As an output of this step, you will have the cluster GWS access token:

Parameter	Variable	Type	Example	Notes
Cluster GWS access token	$outClusterGWSAccessToken	UUID string	9b7682b7-cbce-422f-9bbb-ecda85e61695	The access_token from the response example.

To provision the API key, send a POST request to Digital Channels:

curl --request POST '$nexusURL/nexus/v3/apikeys' \
--header 'Authorization: $outClusterGWSAccessToken' \
--header 'Content-Type: application/json' \
--data '{
    "enabled": true,
    "tenant": "*",
    "name": "Cluster API key",
    "permissions": [
        "nexus:cluster:*"
    ]
}'

The expected response:

{
    "id": "<Your new created Cluster API key>",
    "tenant": "*",
    "name": "Cluster API key",
    "permissions": [
        "nexus:cluster:*"
    ],
    "enabled": true,
    "created": "<Date and time of creation>",
    "revoked": false,
    "expires": false,
    "createdby": "<User who created this APi key>",
    "capacity": 120,
    "frequency": 60
}

As an output of this step, you will have the cluster API key:

Parameter	Variable	Type	Example	Notes
Cluster API Key	$clusterApikey	UUID string	9b7682b7-cbce-422f-9bbb-ecda85e61695	The <Your new created Cluster API key> from the response example

Designer API key

First, follow the instructions above to create a dedicated Designer API key. Set permissions as:

"permissions": [ "nexus:designer:chat" ]

Genesys recommends creating a separate key from the consumer chat API key so that you can update your consumer API key without impacting Designer applications.

curl --request POST '$nexusURL/nexus/v3/apikeys' \
--header 'Authorization: $outGWSAccessToken' \
--header 'Content-Type: application/json' \
--data '{
    "enabled": true,
    "tenant": "$ccId",
    "name": "Designer API key",
    "permissions": [
        "nexus:designer:chat"
    ]
}'

The expected response:

{
    "id": "<Your new created API key>",
    "tenant": "$ccId",
    "name": "Designer API key",
    "permissions": [
        "nexus:designer:chat"
    ],
    "enabled": true,
    "created": "<Date and time of creation>",
    "revoked": false,
    "expires": false,
    "createdby": "<User who created this APi key>",
    "capacity": 120,
    "frequency": 60
}

As an output of this step, you will have the specific tenant API key:

Parameter	Variable	Type	Example	Notes
Designer API Key	$designerApikey	UUID string	9b7682b7-cbce-422f-9bbb-ecda85e61695	The <Your new created API key> from the response example