diff --git a/docs.json b/docs.json index 4e4fbdb91..65660d5cd 100644 --- a/docs.json +++ b/docs.json @@ -222,6 +222,12 @@ "fundamentals/webhooks-legacy" ] }, + { + "group": "Media", + "pages": [ + "fundamentals/presigned-urls" + ] + }, { "group": "User-Roles", "pages": [ diff --git a/fundamentals/presigned-urls.mdx b/fundamentals/presigned-urls.mdx new file mode 100644 index 000000000..1f3b895ec --- /dev/null +++ b/fundamentals/presigned-urls.mdx @@ -0,0 +1,56 @@ +--- +title: "Pre-Signed URLs" +sidebarTitle: "Pre-Signed URLs" +description: "Secure, time-limited access to media files with configurable expiry." +--- + +CometChat generates **pre-signed URLs** for all media files, including images, audio, video, and documents shared in chat. A pre-signed URL embeds a cryptographic signature and an expiry timestamp directly in the URL, so files are accessible only within a defined time window without requiring API credentials on the client side. + +This feature is enabled by default for all newly created apps. Existing apps can opt in from the CometChat dashboard. + +--- + +## How It Works + +When a media file is sent or retrieved, CometChat returns a pre-signed URL in the following format: + +``` +https://media-.cometchat.io//media/?Expires=&Signature=&Key-Pair-Id= +``` + +| Parameter | Description | +| -------------- | -------------------------------------------------------- | +| `Expires` | Unix timestamp after which the URL is no longer valid | +| `Signature` | Cryptographic signature that validates the URL integrity | +| `Key-Pair-Id` | Identifier for the signing key pair used by CometChat | + +Pre-signed URLs are returned across all surfaces - SDK responses, REST API, and webhook payloads. + +--- + +## Configuring the TTL + +The TTL (Time-to-Live) controls how long a generated pre-signed URL remains valid. + +| Setting | Value | +| ------- | ----------- | +| Minimum | 15 minutes | +| Maximum | 1 month | +| Default | 1 day | + +To configure the TTL: + +1. Go to the [CometChat Dashboard](https://app.cometchat.com/apps). +2. Select your app and navigate to **Chat & Messaging** → **Settings**. +3. Under **Pre-Signed URLs**, set your desired TTL value. +4. Save your changes. + + + Pre-Signed URL TTL configuration in CometChat Dashboard + + + +TTL configuration is available on all plans. Changes take effect for all new pre-signed URLs generated after saving; existing URLs retain their original expiry. + + +--- diff --git a/fundamentals/webhooks-overview.mdx b/fundamentals/webhooks-overview.mdx index 5950d4e2e..cde6d2c10 100644 --- a/fundamentals/webhooks-overview.mdx +++ b/fundamentals/webhooks-overview.mdx @@ -32,36 +32,6 @@ Authorization: Basic You can configure this with a username and password known only to your system. -### Token-based files access - -Token-based file access provides improved control over media files through pre-signed URLs. When this feature is enabled, media URLs in webhook payloads may return a 401 Unauthorized response. - -You can enable this feature in the **Settings** section under **Chats** in the CometChat dashboard. Once enabled, it cannot be disabled. - - - - - -To access media files, use the media URL from the webhook payload to obtain a URL secured with a file access token (FAT). This URL redirects to a pre-signed URL that remains valid for 5 minutes. - -**Sample request:** - -```html -curl --location 'https://files-.cometchat.io//media/audio3.mp3' \ - --header 'appId: ' \ - --header 'apiKey: ' -``` - -**Sample response:** - -```json -{ - "data": { - "url": "https://files-.cometchat.io//media/audio3.mp3?fat=" - } -} -``` - *** ## Webhook Best Practices diff --git a/images/presigned-url-ttl-settings.png b/images/presigned-url-ttl-settings.png new file mode 100644 index 000000000..d3f59c0a3 Binary files /dev/null and b/images/presigned-url-ttl-settings.png differ