Skip to content
IAM built for the AI-Era
Logo

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.

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 user 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

    Parameter Value
    Method GET
    Endpoint /api/v1/findusers
    Query Parameters
    • userIdentifier
    • performedBy
    Description Using a user’s email address, retrieve the user information including a temporary user ID.

  2. Fetch Verification Methods

    Parameter Value
    Method GET
    Endpoint /api/v1/verifyidentity
    Query Parameters
    • userId
    Description Using the user ID obtained in step 1, retrieve all available verification methods, each with a corresponding verification ID.

  3. Initiate Verification

    Parameter Value
    Method POST
    Endpoint /api/v1/verifyidentity
    Query Parameters
    Description Start 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

    Parameter Value
    Method GET
    Endpoint /api/v1/identityverificationstatus
    Query Parameters
    • verificationId
    Description Track 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 when using Browser-link verification methods.
notificationLanguage Specifies the language of the notification containing the verification link. This parameter is mandatory when using Browser-link verification methods.