Secure Service Desk API

The Secure Service Desk API allows customers to integrate Secure Service Desk user verification into their existing systems or to build a verification portal for their service desk agents to use. The API is limited to user verification.

The API works as most APIs do, with verification requests sent to Specops Authentication by way of a URL containing the API URL, as well as the search string containing the user to be verified. The API key is sent through the header.

Verification types

Both Quick Verification and Advanced Verification are supported through the API. However, in the case of Quick verification, only those identity services that have been configured to use push notifications can be used.

NOTE
All available Quick Verification identity services will be displayed in the Quick Verification list, regardless of whether or not they have been configured to use push notifications. If a service desk agent uses an identity service as Quick Verification that doesn't have push notifications configured, the verification will fail.

Prerequisites

Prerequisite configuration

The following configurations are required in order to start using the API.

  • API Key: Generate an API key in Authentication Web (see also the section below on generating an API key)
  • Configure Search Attributes: Add the "mail" and/or "userPrincipalName" attributes to the "Search Attributes" in the Gatekeeper Admin Tool. This ensures user searches via the API return results. Without these, user queries will yield no results.
    1. In the Gatekeeper Admin Tool, click on Secure Service Desk
    2. In the User Search settings section, click Edit in the Search attributes row.
    3. Uncheck the Use default value checkbox.
    4. Enter the attributes you would like to use. Comma-separate multiple attributes.
    5. Click OK.

Include API Headers

When making an API call, the following headers need to be included:

Name Required Description
x-api-key Yes The API key generated in the Admin Portal.
x-client-ip Yes The client’s IP address. This IP address will be forwarded to Identity Services to indicate the location of the quick verification initialization. Although required, not all Identity Services support defining the client IP addresses.

Generating API keys

Customers can generate unlimited API keys to use within their organization.

  1. In Authentication Web, click on Service Desk in the left navigation.
  2. Click on the API Keys tab.
  3. In the Friendly Name column, enter a name in the Enter friendly name here field.
  4. Choose Service Desk API in the dropdown in the Resource column.
  5. Click on Generate New API Key.
  6. Copy the API URL and the API Key to a secure location.
    NOTE
    It is very important to copy this data at this stage since it is required to make the API calls, and cannot be displayed again once you leave this page.
  7. Click Save.

Expected Verification Flow

The expected verification flow when making API calls is as follows:

  1. Retrieve User Information
    MethodGET
    Endpoint/api/v1/findusers
    Query Parameters
    • userIdentifier
    • performedBy
    DescriptionUsing a user’s email address, retrieve the user information including a temporary user ID.
  2. Fetch Verification Methods
    MethodGET
    Endpoint/api/v1/verifyidentity
    Query Parameters
    • userId
    DescriptionUsing the user ID obtained in step 1, retrieve all available verification methods, each with a corresponding verification ID.
  3. Initiate Verification
    MethodPOST
    Endpoint/api/v1/verifyidentity
    Query Parameters
    • verificationId
    • notificationMethod (only for advanced verification)
    • notificationLanguage (only for advanced verification)
    DescriptionStart the verification process using a selected verification ID obtained in step 2.
    NOTE
    If the verification fails, the flow must be restarted from step 1 for the same verification method. Alternatively, select a different verification method by using a verification ID from step 2 and restart this step.
  4. Check Verification Status
    MethodGET
    Endpoint/api/v1/verificationstatus
    Query Parameters
    • verificationId
    DescriptionTrack the verification process by querying the status using the verification ID.
    NOTE
    If the status indicates a failure, restart the flow from step 1 to retry the same verification method. Alternatively, select a different verification method by using a verification ID from step 2 corresponding to that method and initiate the process again at step 3. This endpoint should not be called more frequently than once every 2 seconds.

API parameter description

Parameter name Description
userIdentifier The email address or UPN of the user being queried.
performedBy The email address or UPN of the user performing the action.
userId A unique, temporary identifier for the user. Each search call for the same user will generate a new unique user ID.
verificationId A unique, temporary identifier for the verification method. This ID is specific to the user and the selected verification method. It can be used only once to start a verification but may be reused to retrieve the verification status.
notificationMethod Specifies the method by which the user will receive the verification link. This parameter is mandatory for advanced verifications.
notificationLanguage Specifies the language of the notification containing the verification link. This parameter is mandatory for advanced verifications.