API access and API documentation

What it is for

An API account is a key pair consisting of an API key and an API secret with which a third-party system signs in to the EasyUC interface, for example a ticket system or an identity management system that has users and phones created automatically.

The page API Documentation shows the interfaces of exactly this installation in a Swagger interface: endpoints, parameters, responses. It is divided into the areas default, devices, users, groups, reporting, curri, templates, voicemails and globals.

Prerequisites

• An account with the access type Administrator (full access) (ROLE_APP_ADMIN) or the owner account (ROLE_OWNER). Only these accounts see the Administration menu.
• A secure storage location for the secret, for example a password vault.
• The purpose of every API account is defined. Create a separate account for each third-party system so that you can revoke it individually.

Step by step: generating an API account

1. Open the EasyUC Cisco workspace.
2. Select Administration → Integrations & Communication → API Access. The page is called Manage API Users.
3. Click Create at the top right. EasyUC creates the account immediately, without a further form.
4. A notification window with Api key and Api secret appears. Copy both values into your password vault.
5. Close the window with Ok. The list then shows only the API Key.
6. Enter the key and the secret in the third-party system.

Step by step: looking up an interface

1. Select Administration → Integrations & Communication → API Documentation.
2. In the selection list of definitions at the top, select the area, for example users or devices.
3. Expand the endpoint you want and read the parameters, sample bodies and response codes.
4. Pay attention to the parameter for the CUCM connection. Many calls refer to exactly one cluster.

Step by step: revoking an API account

1. Clarify which third-party system uses the key.
2. Click Delete in the row of the key.
3. Confirm the prompt Are you sure?. The account is invalid immediately.

Fields and options

Checking the result and narrowing down errors

• Success: the third-party system signs in with key and secret and receives responses to its calls.
• The secret is lost: delete the account and generate a new one. A secret cannot be displayed again.
• Sign-in is temporarily rejected after several failed attempts: EasyUC slows down repeated failed sign-ins. Correct the credentials and wait a few minutes.
• The API documentation stays empty: it can be retrieved only by signed-in users. Sign in again and load the page.
• Use endpoints and field names from the documentation of your own installation, not from that of another version.
• The audit log knows the actor type API user. There you can trace what was changed through an API account.