Skip to content

Add new attestation

POST/attestations

User Activity Verification API · Attestations

Create a new attestation for the given user.

Required permissionuav.attestation:create

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
fields query array of string No The fields to return in a partial response.

Request body

Content type: application/json

Request body fields

userIdstring (uuid)required
User ID.
titleobjectrequired
A text with optional translations.
Show child attributesHide child attributes
textstringrequired
The default (i.e. English) text. This text is displayed when no translations are provided or the translations don't match the device language. The limitation of the text length applies to translations as well.
Must be at most 100 characters long.
translationsobject
Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language.
questionobjectrequired
A text with optional translations.
Show child attributesHide child attributes
textstringrequired
Must be at most 500 characters long.
translationsobject
Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language.
optionsarray of object
List of answer options. If not specified, options 'yes' and 'no' are used.
Must contain at most 5 items.
An answer option for the attestation's question.
Show child attributesHide child attributes
keystringrequired
The option key. This key is returned when the user selects an option.
Must match the pattern ^[\w,.\-/:]+$. Must be at most 36 characters long.
valueobjectrequired
A text with optional translations.
Show child attributesHide child attributes
textstringrequired
The default (i.e. English) text. This text is displayed when no translations are provided or the translations don't match the device language. The limitation of the text length applies to translations as well.
Must be at most 100 characters long.
translationsobject
Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language.
actionstring
An action URI that Intercept X for Mobile opens when the user selects the option.
Must be at most 2048 characters long.
referencestring
A reference set by the caller of the API and cited when requesting the attestation object.
Must match the pattern ^[\w,.\-/:]+$. Must be at most 256 characters long.
timeoutInSecondsinteger
Timeout in seconds before attestation expires.
Must be ≥ 60 and ≤ 86400.

Request samples

curl -X POST "https://api-<data-region>.central.sophos.com/user-activity-verification/v1/attestations" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>" -H "Content-Type: application/json" -d "{
  \"userId\": \"57e7f67f-6c1a-4580-a031-65f38a229732\",
  \"title\": {
    \"text\": \"Security question\"
  },
  \"question\": {
    \"text\": \"Did you sign in to your account recently?\"
  }
}"


import requests

response = requests.post(
    "https://api-<data-region>.central.sophos.com/user-activity-verification/v1/attestations",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
        "Content-Type": "application/json",
    },
    json={   'userId': '57e7f67f-6c1a-4580-a031-65f38a229732',
    'title': {'text': 'Security question'},
    'question': {'text': 'Did you sign in to your account recently?'}},
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
    "Content-Type" = "application/json"
}
$body = '{
  "userId": "57e7f67f-6c1a-4580-a031-65f38a229732",
  "title": {
    "text": "Security question"
  },
  "question": {
    "text": "Did you sign in to your account recently?"
  }
}'
Invoke-RestMethod -Method POST -Uri "https://api-<data-region>.central.sophos.com/user-activity-verification/v1/attestations" -Headers $headers -Body $body -ContentType "application/json"


package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    req, err := http.NewRequest("POST", "https://api-<data-region>.central.sophos.com/user-activity-verification/v1/attestations", strings.NewReader(`{
  "userId": "57e7f67f-6c1a-4580-a031-65f38a229732",
  "title": {
    "text": "Security question"
  },
  "question": {
    "text": "Did you sign in to your account recently?"
  }
}`))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/user-activity-verification/v1/attestations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "userId": "57e7f67f-6c1a-4580-a031-65f38a229732",
  "title": {
    "text": "Security question"
  },
  "question": {
    "text": "Did you sign in to your account recently?"
  }
}),
});
const data = await response.json();
console.log(data);

Responses

201 — A new attestation was created.

Response fields

userIdstring (uuid)required
User ID.
titleobjectrequired
A text with optional translations.
Show child attributesHide child attributes
textstringrequired
The default (i.e. English) text. This text is displayed when no translations are provided or the translations don't match the device language. The limitation of the text length applies to translations as well.
Must be at most 100 characters long.
translationsobject
Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language.
questionobjectrequired
A text with optional translations.
Show child attributesHide child attributes
textstringrequired
Must be at most 500 characters long.
translationsobject
Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language.
optionsarray of object
List of answer options. If not specified, options 'yes' and 'no' are used.
Must contain at most 5 items.
An answer option for the attestation's question.
Show child attributesHide child attributes
keystringrequired
The option key. This key is returned when the user selects an option.
Must match the pattern ^[\w,.\-/:]+$. Must be at most 36 characters long.
valueobjectrequired
A text with optional translations.
Show child attributesHide child attributes
textstringrequired
The default (i.e. English) text. This text is displayed when no translations are provided or the translations don't match the device language. The limitation of the text length applies to translations as well.
Must be at most 100 characters long.
translationsobject
Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language.
actionstring
An action URI that Intercept X for Mobile opens when the user selects the option.
Must be at most 2048 characters long.
referencestring
A reference set by the caller of the API and cited when requesting the attestation object.
Must match the pattern ^[\w,.\-/:]+$. Must be at most 256 characters long.
idstring (uuid)required
Attestation ID.
tenantobjectrequired
Tenant this resource belong to.
Show child attributesHide child attributes
idstring (uuid)required
namestring
expiresAtstring (date-time)required
Attestation expiration timestamp. After expiration, the attestation is read-only.
statusstringrequired
Attestation status. If the user selected an answer option, the status is 'completed' and the key of the selected answer option is available in 'selectedOption'. If the user didn't select an answer option before the attestation expired, the status is 'expired'. If the user didn't select an answer option yet and the attestation hasn't expired, the attestation is in 'pending' status.
Must be one of: pending, expired, completed.
selectedOptionstring
The key of the answer option the user selected (when status is 'completed'). 'selectedOption' is 'yes' or 'no' for attestations without answer options.

Errors

Status Meaning
400 Request is invalid.
404 Can't find at least one object in the request.
429 Too many requests. See Retry-After header.
500 Internal server error.

All error responses share the same shape — see the error response object.

Response examples

201

{
  "userId": "57e7f67f-6c1a-4580-a031-65f38a229732",
  "title": {
    "text": "Security Question",
    "translations": {
      "de": "Sicherheitsfrage"
    }
  },
  "question": {
    "text": "When was the last time you signed in to your account?",
    "translations": {
      "de": "Wann haben Sie sich das letzte Mal an Ihrem Benutzerkonto angemeldet?"
    }
  },
  "options": [
    {
      "key": "today",
      "value": {
        "text": "Today",
        "translations": {
          "de": "Heute"
        }
      }
    },
    {
      "key": "yesterday",
      "value": {
        "text": "Yesterday",
        "translations": {
          "de": "Gestern"
        }
      }
    },
    {
      "key": "lastWeek",
      "value": {
        "text": "One week ago",
        "translations": {
          "de": "Vor einer Woche"
        }
      }
    },
    {
      "key": "unsure",
      "value": {
        "text": "I don't remember",
        "translations": {
          "de": "Ich wei\u00df es nicht mehr"
        }
      }
    }
  ],
  "id": "e0f14a18-a5ee-4d86-b0c2-cf0a2849ed78",
  "tenant": {
    "id": "d46d9df1-ee5a-44cc-8bf5-252fcc3c16f0"
  },
  "expiresAt": "2021-11-05T09:39:44.638",
  "status": "pending"
}

See the guide for a narrative walkthrough of this API.