User Provisioning API

The User Provisioning API allows you to programmatically create, query the existence of, and delete Users and Agents within Symbee Connect, and also within the backing Amazon Connect Instance.

This API is intended to facilitate automation of user provisioning flows, and therefore only has a limited set of functionality - namely, adding a user, deleting a user, and querying the existence of a user to check whether a user has already previously been provisioned or not.

User Provisioning API Endpoint

User Provisioning API requests are sent as HTTP POST requests, to the following Base API URL. The name of the add, query, or delete operation is then added to the end of this URL depending on which operation you are calling - see details of each operation further below:

Where [global-region.] in the above URL is one of the following, depending on which region your Symbee Connect Environment resides:

• not supplied (defaults to us-east-1)
• us-west-2
• ca-central-1
• eu-west-2
• eu-central-1
• ap-southeast-1
• ap-southeast-2
• ap-northeast-1
• ap-northeast-2
• af-south-1

API Authentication

All POST requests to the API must have the following additional HTTP Headers present on the requests to succeed:

• X-sc-platform-code – static value of “AWS Connect”
• X-sc-company-code – Your Symbee Connect Company Alias
• X-sc-company-environment – Your Symbee Connect Environment name
• X-sc-secrets-region – Your Symbee Connect *AWS Secrets Manager Region* e.g. “us-east-1”
• X-sc-company-api-key – Your AWS Secrets Manager Symbee Connect API Key

Details on the 'X-sc-company-api-key' Header value

You will need to obtain your Symbee Connect API Key programmatically from AWS Secrets Manager.

When you sign up for Symbee Connect and decide to use any of the optional features that require running CloudFormations, the very first CloudFormation you run (see here for reference) installs an automatically rotating API Key into the AWS Account associated with the Symbee Connect Environment. This API key establishes a 2-way trust between you and Symbee Connect, and its value is required as a Header on all API requests.

To obtain the API key, use the AWS Secrets Manager API GetSecretValue action, passing in a SecretId of "SYMBEE_CONNECT_API_KEY". Use the value returned in the SecretString property of the response payload as the value to send in the 'X-sc-company-api-key'' header on Queue Statistics API requests.

Note that the SYMBEE_CONNECT_API_KEY value in Secrets Manager is regularly rotated, so it is best to not cache this value for an extended period of time (no longer than an hour).

Common API Request and Response details

Common Operation Request Payload properties

All API requests (operations) are sent as HTTP POST requests with the payload/body of the request being a valid JSON formatted request object.

All JSON request objects require a tenant property, which is an object in itself, containing three properties - platform, companyCode, and environment - detailed below:

tenant.platform

Value is a string. Use the static value of "AWS Connect".

tenant.companyCode

Value is a string. Use your Symbee Connect Company Alias.

tenant.environment

Value is a string. Use your Symbee Connect Environment name.

Example

{
    "tenant" : {
        "platform": "AWS Connect",
        "companyCode": "abc-gadgets",
        "environment": "prod"
    },
    ...
}

Refer to details further below for additional operation-specific properties related to each specific API request type.

Common Operation Response details

Standard HTTP Response Codes are used as API responses. Therefore HTTP 4xx and 5xx response codes should be treated as failure.

Specifically, a 401 - Unauthorized response indicates you are either using an invalid endpoint URL, or your X-sc request headers are invalid, missing, or malformed, or you API Key is invalid.

A 200 - OK response at least indicates you reached the API endpoint correctly, and your request headers are well-formed. At which point a 200 OK response contains a JSON response object describing the true outcome (success or fail) of the API request, including application-level failure reasons, and possible API request return values for a successful request.

At minimum a 200 OK response will have a result property (string) and a message property (string). A result value of "SUCCESS" indicates the API request was successful. Any other result value indicates failure. For failure responses, the message property provides the reason for failure.

Below lists the possible result values returned:

• SUCCESS
• UNAUTHORIZED
• INVALID_TENANT
• INVALID_ARGUMENTS
• ALREADY_EXISTS
• NOT_SUPPORTED
• NOT_FOUND
• FAIL

Examples

Example 200 - OK response payload for a successful API request:

{
    "result": "SUCCESS",
    "message": "User exists",
    ...
}

Refer to details further below for additional operation-specific response properties contained in the payload related to each specific API request type.

Example 200 - OK response payload for an unsuccessful API request:

{
    "result": "NOT_FOUND",
    "message": "User not found"
}

Add User operation

To make an Add User operation request, add /add-user to the end of the API Endpoint URL. For example:

https://symbeeconnect.com:9443/symbee-admin/api/users/add-user

The Add User payload is a JSON object with the following parameters/properties:

Request Object properties

tenant

Value is an Object - see common request properties further above.

loginUserId

Required. Value is a case-sensitive string. The login id of the user to be created. For environments configured to use SAML SSO authentication, this is usually an email address.

firstName

Required. Value is a string. The first name of the user to be created.

lastName

Required. Value is a string. The last/surname of the user to be created.

primaryEmailAddr

Value is an email address (string). Not applicable, and ignored, for environments configured to use SAML SSO authentication. Required for environments that are linked to an Existing Directory (e.g. AD / Active Directory).

secondaryEmailAddr

Optional. Value is an email address (string). Used for notifications only.

userTemplateName

Required. Value is a string. The name of the Symbee Connect User Template to be used when creating the user.

createInAmazonConnect

Value is a boolean (true or false). Set to true if the requested user is also to be created in the backing Amazon Connect instance of your Symbee Connect environment. If the user is successfully created in Amazon Connect, the Amazon Connect unique ID of the user created is returned in the response payload.

Add User Payload Example

{
    "tenant" : {
        "platform": "AWS Connect",
        "companyCode": "abc-gadgets",
        "environment": "prod"
    },
    "loginUserId": "mmars@abc-gadgets.com",
    "firstName": "Mike",
    "lastName": "Mars",
    "userTemplateName": "StandardAgent",
    "createInAmazonConnect": true
}

Add User Response Example

{
    "result": "SUCCESS",
    "message": "User Created",
    "connectUserId": "a5953a27-xxxx-45b3-xxxx-43b66d9e7bd1"
}

Query User Existence operation

To make a Query Existence operation request, add /query-existence to the end of the API Endpoint URL. For example:

https://symbeeconnect.com:9443/symbee-admin/api/users/query-existence

The Query Existence payload is a JSON object with the following parameters/properties:

Request Object properties

tenant

Value is an Object - see common request properties further above.

loginUserId

Required. Value is a case-sensitive string. The login id of the user to look up.

Query Existence Payload Example

{
    "tenant": {
        "platform": "AWS Connect",
        "companyCode": "symbeedevomni",
        "environment": "dev"
    },
    "loginUserId": "mmars@abc-gadgets.com"
}

Query Existence Response Example

Example of querying a User that exists in Symbee Connect but not in Amazon Connect:

{
    "result": "SUCCESS",
    "message": "User exists",
    "amazonConnectStatus": "NOT_FOUND",
    "connectUserId": null
}

Example of querying a User that exists in both Symbee Connect and Amazon Connect:

{
    "result": "SUCCESS",
    "message": "User exists",
    "amazonConnectStatus": "EXISTS",
    "connectUserId": "a5953a27-xxxx-45b3-xxxx-43b66d9e7bd1"
}

Example of querying a User that doesn't exist:

{
    "result": "NOT_FOUND",
    "message": "User not found",
    "amazonConnectStatus": null,
    "connectUserId": null
}

Delete User operation

To make an Delete User operation request, add /delete-user to the end of the API Endpoint URL. For example:

https://symbeeconnect.com:9443/symbee-admin/api/users/delete-user

The Delete User payload is a JSON object with the following parameters/properties:

Request Object properties

tenant

Value is an Object - see common request properties further above.

loginUserId

Required. Value is a case-sensitive string. The login id of the user to delete.

Delete User Payload Example

{
    "tenant": {
        "platform": "AWS Connect",
        "companyCode": "symbeedevomni",
        "environment": "dev"
    },
    "loginUserId": "mmars@abc-gadgets.com"
}

Delete User Response Example

Example of deleting a user that exists.

{
    "result": "SUCCESS",
    "message": "User profile deleted."
}

Example of deleting a user that does not exist.

{
    "result": "NOT_FOUND",
    "message": "User not found"
}