The API Keys page

In addition to using the Eyes Test Manager to support user interaction with your tests and test results, Eyes allows applications to interact with your tests and test results on your behalf. To support this means of working, you need to use API Keys with associated permission types that authorize or restrict the application from using the API to perform certain activities. You can generate API Keys for use by a team or by a specific user.

The API Keys page displays a list of API Keys that are allocated to teams and team members. Using the tools on the page, you can assign users with secure keys which support and control the activities they can perform via the Eyes API, such as:
  • Running tests
  • Viewing test results
  • Extracting data from the test results
  • Editing and saving tests
  • Accepting or rejecting checkpoint diffs
  • Updating baselines
  • Merging branch baselines
This section deals with the API Keys page and the operations that you can perform on the page.
  1. API Keys page layout
  2. API Key permission types
  3. Adding new API Keys
  4. Editing an API Key
  5. Copying an API Key
  6. Deleting Api Keys

API Keys page layout

You can access the API Keys page by clicking the API Keys tile on the Admin panel.

The API Keys page displays a table in which each row lists an API Key associated with a team or team member.

API Key details displayed by default in the table are:
  1. Key
  2. Team
  3. User
  4. Permissions
  5. Purpose
  6. Expires At
  7. Last Access
Additional parameters that you can display in the table by clicking on Edit Columns are:
  1. Team ID
  2. Created At
  3. Created By
  4. Disabled
  5. Expired

API Key properties

The API Key properties are properties that describe the API Key and are used when generating an API Key. All properties must be entered unless noted as optional in the description below.

Key
Lists the actual API Key and is a display-only field. The API Key is issued to users by name. It should be treated as confidential and not shared with other users.
Enable
Indicates whether the API Key is available for use. If the property is selected, the API Key is available for use. If the property is not selected, the API Key is disabled.
Team
The name of the Team with which the API Key is associated.
User
The name of the User with which the API Key is associated.
Permissions
The permission types that can be assigned to the API Key.
  1. Read
  2. Execute
  3. Write
  4. Merge
See API Key permission types for more informationdetails.
Expiry
Shows the date on which the API Key is automatically disabled. This is an optional property. To use the API Key beyond this date requires an administrator to either extend the expiry date or manually enable the API Key.
Purpose
Allows you to input a description of what the API is used for. The property supports input as free text. This an optional property.
Last access
Lists the time and date stamp that indicates the most recent time the API Key was used.
Team ID
Lists an internal ID that is assigned to the team when the team is created. Customer Services may request the ID when handling a customer request that relates to the team.
Created at
Lists the date and time stamp that indicates when the API Key was created.
Created by
Lists the name of the Administrator that created the API Key.
Disabled
Displays a selected checkbox if the API Key is disabled.
Expired
Displays a selected checkbox if the API Key has expired.

API Key permission types

There are several API Key permission types that you can assign when creating or editing an API Key.

Read
Allows users to access tests and test results, but does not allow them to execute tests, change data through the API, or make any changes to the tests.
Execute
Allows users to execute tests but does not allow them to access the tests and test results, change data through the API, or make any changes to the tests.
Write
Allows users to access the test results, make and save changes to test results, save such changes to the baselines, and merge branch baselines.
Merge
Allows users to use the API to merge branch baselines but does not support read, execute, or any write operations other than merging branches.

Test manager user permissions and API Key permissions

When you assign an API Key to a user, the API Key permissions can only include a subset of the permissions that are set for their given team. If the user's team has View only user permissions, the user cannot be granted an API Key with more extensive permissions (e.g. write permissions).

Adding new API Keys

You can add a new API Key in the Add API Key dialog box.

To add a new API Key:
  1. Click Add a new API Key in the API Keys toolbar to open the Add API Key dialog box.
  2. Select a team from the Team drop-down menu.
  3. Enter the user's email address in the User edit box. Click in the edit field and type an email address or select a team member from the drop-down list. Skip this step if you want to create an API Key for a Team only.
  4. Select one or more options from the Permissions group to set the user profile.
  5. Optionally, you can enter a free text comment stating the purpose of the API key in the Purpose edit field.
  6. Optionally, you can set an expiry date for the API Key from the Expiry drop-down calendar.
  7. Click Add.

The new API Key is added to the API Keys list.

Editing an API Key

You may need to modify the parameters set for a particular API Key for a number of reasons. These may include:
  1. Disabling the API Key
  2. Changing the API Key permissions
  3. Setting the API Key expiry date

You make these modifications in the Edit API Key dialog box.

Accessing the Edit API Key dialog box

To access the Edit API Key dialog box:
  1. Open the API Keys page.
  2. Filter for or identify the row in the API Keys table that contains the API Key you want to edit.
  3. Click anywhere in the row to open the Edit API Key dialog box.
To edit an API Key:
  1. Access the Edit API Key dialog box as described above.
  2. Make any required changes to the API Key parameters.
  3. Click Apply to save the changes and close the Edit API Key dialog box.

Disabling an API Key

Disabling an API Key prevents the team or user from using the API to perform test activities that are supported by the key. Disabling the use of an API Key in this way allows you to enable its use at a later time as opposed to deleting the API Key, which erases the key from the system.

To disable an API Key:
  1. Access the Edit API Key dialog box as described above.
  2. Clear the Enable option to disable use of the API Key.
  3. Click Apply to save the changes and close the Edit API Key dialog box.

Changing the API Key permissions

You may need to change API Key permissions for a user. Note that the Test manager user permissions affect the API Key permission options that are available. This is an operation performed on the Teams page. See Setting user permissions for more information.

To change the API Key permissions:
  1. Access the Edit API Key dialog box as described above.
  2. Change the Permissions options as required for the API Key.
  3. Click Apply to save the changes and close the Edit API Key dialog box.

Setting the API Key expiry date

You can set an expiry date for an API Key. If you reach the expiry date, the API Key is disabled and users are prevented from using that API Key. In the API Keys table, an orange-colored warning symbol next to an API Key indicates that it has expired.

To set the API Key expiry date:
  1. Access the Edit API Key dialog box as described above.
  2. Click on the Expiry drop-down calendar field and change the Expiry date for the API Key.
  3. Click Apply to save the changes and close the Edit API Key dialog box.

Copying an API Key

To allow tests to interact with Eyes you must set the relevant API Key in your application code using the class$configuration$setapikey$method . Alternatively you can set the environment variable APPLITOOLS_API_KEY to the vale of the API Key. For that purpose, you can copy an API Key to the clipboard from the API Keys page or from the Edit API Key dialog box.

To copy an API Key:
  1. Open the API Keys page.
  2. Filter for or identify the row in the API Keys table that contains the API Key you want to copy.
  3. Hover over the row and click Copy key to clipboard .

Note: When the Edit API Key dialog box is open, the Copy key to clipboard link is adjacent to the Key field.

See also How to obtain your API keythis latter method is convenient for use by users who are do not have admin rights and can not access the admin pages.

Deleting Api Keys

You can delete one or more API keys by selecting the checkbox to the left of the API key and then clicking on the button on the tool bar. You can also delete an API key by clicking on the Delete button in the API Key dialog.