Video Verification Retrieval & Playback

Available from: v1.0.71

Overview

During the mandate setup flow, tenants record a short video verification — stating their name, the collection amount, and the property or purpose. From v1.0.71, authorised admin users can retrieve and play back these recordings securely, both within the mandate detail page and via API.

This capability supports fraud investigation, compliance review, and dispute resolution workflows.

---

How It Works

1. A mandate's video verification recording is stored in S3.
2. When an admin user requests to view the recording, the system generates a presigned S3 URL that grants temporary, read-only access to the file.
3. The URL expires after 1 hour — it cannot be shared or reused beyond this window.
4. The recording is streamed inline in the mandate detail page using a built-in video player.
5. The access event is written to the audit log, recording the user, timestamp, and mandate reference.

---

Access Control

Requirement	Detail
Authentication	Must be a logged-in organisation member
Role	Admin role required
URL expiry	1 hour from generation
Audit trail	Every access is logged as an audit event

Attempts to access the endpoint without the admin role will be rejected.

---

Mandate Detail Page

On the mandate detail page, admins with the appropriate role will see an inline video player rendered directly in the verification section. No additional navigation is required — the presigned URL is fetched on demand when the player is loaded.

---

API Endpoint

The video URL generation is exposed as an API endpoint for consuming applications (e.g. agentOS) to surface recordings in their own UI.

Request

GET /api/mandates/:mandateId/video-verification

Parameter	Type	Description
mandateId	string	The unique identifier of the mandate

Headers:

Authorization: Bearer <token>

The authenticated user must have the admin role within their organisation.

Response

{
  "url": "https://s3.amazonaws.com/...?X-Amz-Expires=3600&...",
  "expiresAt": "2025-01-01T13:00:00.000Z"
}

Field	Type	Description
url	string	Presigned S3 URL for the video recording
expiresAt	string	ISO 8601 timestamp when the URL expires

Error Responses

Status	Reason
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	Authenticated user does not have admin role
404 Not Found	Mandate not found, or no video recording exists for this mandate

---

Audit Log

Every time the video verification URL is generated (whether via the UI or the API), an audit event is recorded with the following details:

• Event type: video_verification.accessed
• Actor: The authenticated user (ID and email)
• Mandate: The mandate reference
• Timestamp: UTC time of access

Audit events can be retrieved via the standard audit log API for compliance and investigation purposes.

---

Notes

• Presigned URLs should not be stored or redistributed — generate a fresh URL each time access is needed.
• If a mandate does not have a video verification recording (e.g. it was created before this feature was available), the endpoint will return a 404.
• URL expiry is fixed at 1 hour and is not configurable per request.