Getting started

This guide explains how to use the User Activity Verification API to send attestations to your users. After reading this guide, you should be able to use the User Activity Verification API to create attestations and get their results.

Requirements¶

This guide assumes that you're a Sophos Central customer and already have created a "service principal" for using Sophos Central APIs. For details on creating a "service principal", see Getting Started as a Tenant.

The device to receive an attestation must be an Android device, iPhone, or iPad with Sophos Intercept X for Mobile managed by Sophos Central. For details on setting up mobile devices in Sophos Central, see Sophos Central Customer documentation: Mobile devices.

Terminology¶

Before you use the User Activity Verification API, here are a few terms you should know:

• Attestation: A short question with predefined answers that you send to a user's mobile device.
• Device: An Android device, iPhone, or iPad. To receive an attestation, Sophos Intercept X for Mobile must be installed and must be managed by Sophos Central.
• User: A Sophos Central user assigned to a mobile device.

Overview¶

Attestations are small questions with predefined answers you send to a user's mobile device. The user can easily respond to the question by clicking one of the provided answers.

To receive attestations, users need an Android device, iPhone, or iPad with Sophos Intercept X for Mobile managed by Sophos Central. Users can respond to an attestation from any of their devices on which the attestation is shown.

You can add actions to an answer that take the form of a URI. Intercept X for Mobile will open the URI when the user selects the answer. Only https:// and tel:// schemes are supported for use with actions. If the device doesn't support the URI scheme (for example, most tablets don't support tel://), the selected answer is still sent to Sophos Central, but Intercept X for Mobile doesn't open the action URI.

Attestations have a validity period (10 minutes by default) for the user to provide an answer.

The User Activity Verification API covers both sending and receiving attestation data.

API operation fundamentals¶

Making API requests¶

In this guide, we use the curl command-line tool for making requests to the User Activity Verification API.

For information on installing and using curl, see the curl website.

General request form¶

When using curl, a request to the User Activity Verification API has the following general form:

curl -X<method> -H "Authorization: Bearer <jwt>" -H "X-Tenant-ID: <tenant-id>" <data-region>/<path>

The command includes the following placeholders:

• <method>: The request method. For the User Activity Verification API, this is either GET or POST.
• <tenant-id>: The ID of the tenant you want to query.
• <jwt>: The JWT access token returned when the IDP authenticates the service principal.
• <data-region>: The regional API host in the data geography where the tenant data is located.
• <path>: The request path for the API operation, for example user-activity-verification/v1/attestations.

For information on how to find out your <tenant-id>, <jwt>, and <data-region> values, see Getting Started as a Tenant.

For brevity, the API descriptions in this guide only specify the request method and path. For example:

POST /user-activity-verification/v1/attestations

To make an actual API request, you must expand this to the full form shown above.

Return status¶

All API requests return HTTP status codes 200 or 201 when successful.

Get user ID¶

To create an attestation, you must provide the Sophos Central user ID of the user.

To get the ID, you can use the following request to the Common API:

GET /common/v1/directory/users

For details, see the Common API reference.

Localized texts¶

When creating an attestation, you can provide localized versions of every text field, as shown in the Advanced attestation example.

The locale key you provide in the request must match the locale that is set on the device. Otherwise, the default texts are used. For example, when you provide strings for Portuguese (locale pt) and the device uses Brazilian-Portuguese (pt-BR), the locales don't match, and your default texts are displayed.

Date and time formatting¶

You can include ISO 8601 timestamps in every text field of an attestation and render them according to the time zone and locale configured on the device.

The general format is as follows:

${<presentation type>/<ISO 8601 timestamp value>/<presentation style>}

<presentation type> is one of datetime, date, or time. <presentation style> is one of full, long, medium, or short. For details, see below.

Examples:

${datetime/2022-01-01T12:00:00Z/medium}
${date/2022-01-01T12:00:00Z/short}
${time/2022-01-01T12:00:00Z/long}

Available <presentation type> values are:

Available <presentation style> values are:

• full
• long
• medium
• short

From full to short, fewer details are shown, and the presentation gets more compact. The actual information shown depends on the <presentation type> value. See the following examples.

Examples:

All examples assume a timestamp of "2021-02-22T14:00:00+00:00Z", a device offset of +8 hours, and a device locale en.

API operation examples¶

Create simple attestation¶

The following example shows the most basic request for creating an attestation.

There are no answer options specified, so the default answer options yes and no apply.

There's no timeout specified, so the default timeout of 10 minutes applies. If the user doesn't answer in that period, the attestation expires.

POST /user-activity-verification/v1/attestations

Request body:

{
    "userId": "391e5ccc-6111-400d-92aa-c940bde92a4d",
    "title": {
        "text": "Action required"
    },
    "question": {
        "text": "Are you feeling well?"
    }
}

When the attestation is created successfully, the response contains the attestation object like this:

{
    "id": "a21842ae-e4c2-4f3c-ba4e-89b34c043482",
    "tenant": {
        "id": "adcc7218-8588-4f4f-9970-8d7205bd0d48"
    },
    "userId": "391e5ccc-6111-400d-92aa-c940bde92a4d",
    "title": {
        "text": "Action required"
    },
    "question": {
        "text": "Are you feeling well?"
    },
    "expiresAt": "2022-05-11T07:30:41.560Z",
    "status": "pending"
}

Create advanced attestation¶

The following example shows an advanced request for an attestation with custom answer options, timeout, and localized texts.

POST /user-activity-verification/v1/attestations

Request body:

{
    "userId": "391e5ccc-6111-400d-92aa-c940bde92a4d",
    "title": {
        "text": "Action required",
        "translations": {
            "de": "Aktion erforderlich"
        }
    },
    "question": {
        "text": "What is your favorite pet?",
        "translations": {
            "de": "Was ist dein Lieblingshaustier?"
        }
    },
    "options": [
        {
            "key": "dog",
            "value": {
                "text": "Dog",
                "translations": {
                    "de": "Hund"
                }
            }
        },
        {
            "key": "cat",
            "value": {
                "text": "Cat",
                "translations": {
                    "de": "Katze"
                }
            }
        },
        {
            "key": "horse",
            "value": {
                "text": "Horse",
                "translations": {
                    "de": "Pferd"
                }
            }
        }
    ],
    "timeoutInSeconds": 3600
}

When the attestation is created successfully, the response contains the attestation object like this:

{
    "id": "a21842ae-e4c2-4f3c-ba4e-89b34c043482",
    "tenant": {
      "id": "adcc7218-8588-4f4f-9970-8d7205bd0d48"
    },
    "userId": "391e5ccc-6111-400d-92aa-c940bde92a4d",
    "title": {
        "text": "Action required",
        "translations": {
            "de": "Aktion erforderlich"
        }
    },
    "question": {
        "text": "What is your favorite pet?",
        "translations": {
            "de": "Was ist dein Lieblingshaustier?"
        }
    },
    "options": [
        {
            "key": "dog",
            "value": {
                "text": "Dog",
                "translations": {
                    "de": "Hund"
                }
            }
        },
        {
            "key": "cat",
            "value": {
                "text": "Cat",
                "translations": {
                    "de": "Katze"
                }
            }
        },
        {
            "key": "horse",
            "value": {
                "text": "Horse",
                "translations": {
                    "de": "Pferd"
                }
            }
        }
    ],
    "expiresAt": "2022-05-11T09:11:40.776Z",
    "status": "pending"
}

Create attestation with answer actions¶

The following example shows an advanced request for an attestation with one answer option containing an action.

POST /user-activity-verification/v1/attestations

Request body:

{
    "userId": "391e5ccc-6111-400d-92aa-c940bde92a4d",
    "title": {
        "text": "Question"
    },
    "question": {
        "text": "Do you know that User Activity Verification API supports actions?"
    },
    "options": [
        {
            "key": "yes",
            "value": {
                "text": "Yes"
            }
        },
        {
            "key": "no",
            "value": {
                "text": "No"
            }
        },
        {
            "key": "show-docs",
            "value": {
                "text": "Learn more"
            },
            "action": "/guides/user-activity-verification.md"
        }
    ]
}

When the attestation is created successfully, the response contains the attestation object like this:

{
    "id": "a21842ae-e4c2-4f3c-ba4e-89b34c043482",
    "tenant": {
        "id": "adcc7218-8588-4f4f-9970-8d7205bd0d48"
    },
    "userId": "391e5ccc-6111-400d-92aa-c940bde92a4d",
    "title": {
        "text": "Question"
    },
    "question": {
        "text": "Do you know that User Activity Verification API supports actions?"
    },
    "options": [
        {
            "key": "yes",
            "value": {
                "text": "Yes"
            }
        },
        {
            "key": "no",
            "value": {
                "text": "No"
            }
        },
        {
            "key": "show-docs",
            "value": {
                "text": "Learn more"
            },
            "action": "/guides/user-activity-verification.md"
        }
    ],
    "expiresAt": "2023-03-31T08:02:37.143Z",
    "status": "pending"
}

Get attestation¶

Use this API to get the status of an attestation. You can get the attestation results up to 48 hours after the user has responded to the attestation.

GET /user-activity-verification/v1/attestations/{attestationId}

The above request returns an attestation object like this:

{
    "id": "a21842ae-e4c2-4f3c-ba4e-89b34c043482",
    "tenant": {
        "id": "adcc7218-8588-4f4f-9970-8d7205bd0d48"
    },
    "userId": "391e5ccc-6111-400d-92aa-c940bde92a4d",
    "title": {
        "text": "Action required"
    },
    "question": {
        "text": "Are you feeling well?"
    },
    "expiresAt": "2022-05-11T07:30:41.560Z",
    "status": "completed",
    "selectedOption": "yes"
}

After the user has responded, status is completed and selectedOption contains the key of the answer option they selected. If you didn't provide custom answer options when creating the attestation, selectedOption is either yes or no.

If the user didn't respond to the attestation until the expiresAt date, status is expired.

Additional resources¶

For a comprehensive description of the User Activity Verification API, see the API reference.