openapi: 3.0.0 info: description: >- This is the OAS 3.0 specification for the User Activity Verification API in Sophos Central. version: 1.1.0 contact: name: Sophos Central APIs email: apis@sophos.com url: 'https://developer.sophos.com' title: User Activity Verification API tags: - name: Attestations description: 'Create attestations, poll attestation status.' servers: - url: 'https://api-{dataRegion}.central.sophos.com/user-activity-verification/v1' description: Regional service in the production environment. variables: dataRegion: description: Data region where tenant data is stored. default: eu01 enum: - eu01 - eu02 - us01 - us03 security: - bearerAuth: [] paths: /attestations: post: x-soph-permissions: - 'uav.attestation:create' summary: Add new attestation description: Create a new attestation for the given user. operationId: createAttestation tags: - Attestations parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string requestBody: description: New attestation request. required: true content: application/json: schema: allOf: - type: object description: Request to create an attestation. required: - userId - title - question properties: userId: description: User ID. type: string format: uuid title: type: object description: A text with optional translations. required: - text properties: text: type: string description: >- 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. maxLength: 100 translations: type: object description: >- Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language. additionalProperties: type: string description: >- Translated text for the language specified by the key. question: allOf: - type: object description: A text with optional translations. required: - text properties: text: type: string description: >- 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. maxLength: 100 translations: type: object description: >- Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language. additionalProperties: type: string description: >- Translated text for the language specified by the key. - type: object properties: text: type: string maxLength: 500 options: description: >- List of answer options. If not specified, options 'yes' and 'no' are used. type: array maxItems: 5 items: type: object description: An answer option for the attestation's question. required: - key - value properties: key: description: >- The option key. This key is returned when the user selects an option. type: string maxLength: 36 pattern: '^[\w,.\-/:]+$' value: type: object description: A text with optional translations. required: - text properties: text: type: string description: >- 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. maxLength: 100 translations: type: object description: >- Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language. additionalProperties: type: string description: >- Translated text for the language specified by the key. action: description: >- An action URI that Intercept X for Mobile opens when the user selects the option. type: string maxLength: 2048 reference: description: >- A reference set by the caller of the API and cited when requesting the attestation object. type: string maxLength: 256 pattern: '^[\w,.\-/:]+$' - type: object description: >- Attestation request. Creates an attestation for the given user. properties: timeoutInSeconds: description: Timeout in seconds before attestation expires. type: integer default: 600 minimum: 60 maximum: 86400 examples: createRequestMinimum: summary: Minimum description: >- This is an example attestation with default answer options ('yes' and 'no') and default timeout (600 seconds). value: userId: 57e7f67f-6c1a-4580-a031-65f38a229732 title: text: Security question question: text: Did you sign in to your account recently? createRequestWithTranslations: summary: With translations description: >- This is an example attestation with four answer options and a timeout of 5 minutes. The attestation includes German translation. On devices with other languages, the default (i.e. English) text is displayed. value: 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ß es nicht mehr timeoutInSeconds: 300 responses: '201': description: A new attestation was created. content: application/json: schema: allOf: - type: object description: Request to create an attestation. required: - userId - title - question properties: userId: description: User ID. type: string format: uuid title: type: object description: A text with optional translations. required: - text properties: text: type: string description: >- 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. maxLength: 100 translations: type: object description: >- Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language. additionalProperties: type: string description: >- Translated text for the language specified by the key. question: allOf: - type: object description: A text with optional translations. required: - text properties: text: type: string description: >- 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. maxLength: 100 translations: type: object description: >- Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language. additionalProperties: type: string description: >- Translated text for the language specified by the key. - type: object properties: text: type: string maxLength: 500 options: description: >- List of answer options. If not specified, options 'yes' and 'no' are used. type: array maxItems: 5 items: type: object description: An answer option for the attestation's question. required: - key - value properties: key: description: >- The option key. This key is returned when the user selects an option. type: string maxLength: 36 pattern: '^[\w,.\-/:]+$' value: type: object description: A text with optional translations. required: - text properties: text: type: string description: >- 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. maxLength: 100 translations: type: object description: >- Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language. additionalProperties: type: string description: >- Translated text for the language specified by the key. action: description: >- An action URI that Intercept X for Mobile opens when the user selects the option. type: string maxLength: 2048 reference: description: >- A reference set by the caller of the API and cited when requesting the attestation object. type: string maxLength: 256 pattern: '^[\w,.\-/:]+$' - type: object description: Attestation. required: - id - tenant - expiresAt - status properties: id: description: Attestation ID. type: string format: uuid tenant: description: Tenant this resource belong to. type: object required: - id properties: id: type: string format: uuid name: type: string expiresAt: description: >- Attestation expiration timestamp. After expiration, the attestation is read-only. type: string format: date-time status: type: string description: >- 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. enum: - pending - expired - completed selectedOption: description: >- The key of the answer option the user selected (when status is 'completed'). 'selectedOption' is 'yes' or 'no' for attestations without answer options. type: string examples: pendingAttestation: summary: Attestation in pending state description: This is an example attestation with 'pending' status. value: 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ß 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 '400': description: Request is invalid. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find at least one object in the request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '429': description: Too many requests. See Retry-After header. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/attestations/{attestationId}': get: x-soph-permissions: - 'uav.attestation:read' summary: Get attestation description: Get an attestation by ID. operationId: getAttestationById tags: - Attestations parameters: - in: path name: attestationId description: Attestation ID. required: true schema: type: string format: uuid - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string responses: '200': description: Attestation object for given attestation ID. content: application/json: schema: allOf: - type: object description: Request to create an attestation. required: - userId - title - question properties: userId: description: User ID. type: string format: uuid title: type: object description: A text with optional translations. required: - text properties: text: type: string description: >- 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. maxLength: 100 translations: type: object description: >- Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language. additionalProperties: type: string description: >- Translated text for the language specified by the key. question: allOf: - type: object description: A text with optional translations. required: - text properties: text: type: string description: >- 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. maxLength: 100 translations: type: object description: >- Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language. additionalProperties: type: string description: >- Translated text for the language specified by the key. - type: object properties: text: type: string maxLength: 500 options: description: >- List of answer options. If not specified, options 'yes' and 'no' are used. type: array maxItems: 5 items: type: object description: An answer option for the attestation's question. required: - key - value properties: key: description: >- The option key. This key is returned when the user selects an option. type: string maxLength: 36 pattern: '^[\w,.\-/:]+$' value: type: object description: A text with optional translations. required: - text properties: text: type: string description: >- 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. maxLength: 100 translations: type: object description: >- Optional key/value pairs of RFC 4646 language tag and translated version of the default text for that language. additionalProperties: type: string description: >- Translated text for the language specified by the key. action: description: >- An action URI that Intercept X for Mobile opens when the user selects the option. type: string maxLength: 2048 reference: description: >- A reference set by the caller of the API and cited when requesting the attestation object. type: string maxLength: 256 pattern: '^[\w,.\-/:]+$' - type: object description: Attestation. required: - id - tenant - expiresAt - status properties: id: description: Attestation ID. type: string format: uuid tenant: description: Tenant this resource belong to. type: object required: - id properties: id: type: string format: uuid name: type: string expiresAt: description: >- Attestation expiration timestamp. After expiration, the attestation is read-only. type: string format: date-time status: type: string description: >- 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. enum: - pending - expired - completed selectedOption: description: >- The key of the answer option the user selected (when status is 'completed'). 'selectedOption' is 'yes' or 'no' for attestations without answer options. type: string examples: pendingAttestation: summary: Attestation in pending state description: This is an example attestation with 'pending' status. value: 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ß 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 completedAttestation: summary: Attestation in completed state description: >- This is an example attestation with 'completed' status and answer option 'lastWeek' selected by the user. value: 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ß es nicht mehr id: e0f14a18-a5ee-4d86-b0c2-cf0a2849ed78 tenant: id: d46d9df1-ee5a-44cc-8bf5-252fcc3c16f0 expiresAt: '2021-11-05T09:39:44.638' status: completed selectedOption: lastWeek '404': description: Can't find attestation. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '429': description: Too many requests. See Retry-After header. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Internal server error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT