Guides
Start typing to search…

Implementation Guide: Media File Authentication

Overview

Starting with the upcoming release of our platform, all media files served from our system will require a key-based authentication mechanism. This change affects all files retrieved via:

  • API responses
  • Event payloads trough PubSub or Webhooks

The authentication key will be embedded in the media file URL and must be present when accessing the file.

⚠️ Important: All existing media links that integrators are currently using will become invalid, because they do not contain the required ?key parameter.

Key Authentication

  • Every media file link returned from our system will include a time-limited key as a query parameter in the URL.
  • This key must be used as-is (the parameter is ?key). Altering the URL or attempting to access the file without the key will result in an authentication failure.
  • The key has an expiration time, after which the link will no longer be valid.

Expiration Policy

  • Initially, all keys for integrator systems will be issued with a 30-day expiration.
  • The expiration will also be explicitly included as a query parameter in the returned URL using the format expiresAt=<timestamp>.
  • Example: expiresAt=2025-06-16T14%3A52%3A36.385565Z
  • This means that after a successful response from our system, you will have 30 days to download the media file.
  • After the expiration, you must request the same API through which you originally obtained the media link in order to generate a new valid media link.
  • If the file was delivered through Pub/Sub or Webhook events, you will need to issue a GET request to the parent resource (the resource that originally contained the media references) in order to retrieve the files again with new, valid expiration links.
  • In the future, expiration times will be shortened, and we will provide advance notice before this change.

Example

When fetching a media file from the API, the response may look like:

{
  "fileUrl": "https://media.ship.cars/files/12345?key=abcdef123456&expiresAt=2025-06-16T14%3A52%3A36.385565Z"
}
  • key: The authentication key granting temporary access.
  • expiresAt: The timestamp when the link will expire (URL-encoded ISO 8601 format).

To download the file, simply request the fileUrl as provided.

Action Required by Integrators

  1. Update your systems to handle time-limited URLs with the ?key and expiresAt parameters.

  2. Be aware that all existing media links will become invalid because they do not include the required parameters.

  3. Ensure that media files are downloaded within 30 days of receiving the link (expiration time will be included as the expiresAt parameter).

  4. After expiration:

    • If the file was obtained via API, request the same API again to generate a fresh, valid media link.
    • If the file was obtained via Pub/Sub or Webhook event, send a GET request to the parent resource in order to retrieve the files again with new expiration links.

Future Considerations

  • The 30-day expiration is only the initial setting for integrators. In the future, expiration times will be shortened.
  • The expiresAt timestamp is included in the query parameters of the URL, so integrators can programmatically verify how long a link remains valid.
  • We will communicate any changes to expiration policies in advance.

Support

If you have any questions or need guidance updating your integration, please contact our support team at [email protected].

Updated 2 days ago