Signed URLs

Vault exposes a REST API that lets you obtain temporary, time-limited URLs (“signed URLs”) for every asset it stores: the original recording (.mp4), the thumbnail (_thumbnail.jpg), the sprite (_sprite.jpg), the redacted version, exports, and any other generated file.

This page documents the endpoints you need to call, the authentication model, and gives ready-to-use examples.

Authentication

All /api/storage/* endpoints described below are not behind JWT. They authenticate per-request using account credentials that you provision in the Vault admin UI (see Accounts).

Two HTTP headers are always required:

The account also has a default provider assigned to it; you can override it per request via X-Kerberos-Storage-Provider (single-file endpoints) or via the JSON body (bulk endpoint).

Warning: Treat the access key + secret pair as a long-lived credential. Do not embed them in frontend code or share them with end-users. The signed URLs the API returns are the only artefacts that are safe to hand out, and only for the duration of their expiry.

How asset filenames are derived

When the Hub pipeline processes a recording, every generated asset is stored on the same provider, in the same username/ directory, using a deterministic filename derived from the original recording. For a recording named:

account-a/1776427171_1-1_frontdoor_402-263-805-680_801_29960.mp4

the pipeline generates:

To obtain a signed URL for any of them, you call the same endpoint and just pass the corresponding filename.

1. Single file — GET /api/storage

Returns a signed URL for one file.

Request headers

Response

{
  "data": "https://<provider-host>/...<signed-query-string>..."
}

Example — fetch a signed URL for a thumbnail:

GET http://localhost:8085/api/storage HTTP/1.1
X-Kerberos-Storage-FileName: account-a/1776427171_1-1_frontdoor_402-263-805-680_801_29960_thumbnail.jpg
X-Kerberos-Storage-Provider: primary-provider
X-Kerberos-Storage-AccessKey: <vault-access-key>
X-Kerberos-Storage-SecretAccessKey: <vault-secret-access-key>

curl -s "http://localhost:8085/api/storage" \
  -H "X-Kerberos-Storage-FileName: account-a/1776427171_..._29960_thumbnail.jpg" \
  -H "X-Kerberos-Storage-Provider: primary-provider" \
  -H "X-Kerberos-Storage-AccessKey: $VAULT_ACCESS_KEY" \
  -H "X-Kerberos-Storage-SecretAccessKey: $VAULT_SECRET"

2. Bulk — POST /api/storage/bulk

Returns signed URLs for any number of files in a single round-trip. This is the most efficient way to fetch all signed URLs for a given media (recording + thumbnail + sprite + redacted + …).

Request headers

Request body

An array of MediaUrlRequest:

[
  {
    "filename": "account-a/1776427171_..._29960.mp4",
    "provider": "primary-provider",
    "uriExpiryTime": "24h"
  },
  {
    "filename": "account-a/1776427171_..._29960_thumbnail.jpg",
    "provider": "primary-provider",
    "uriExpiryTime": "24h"
  },
  {
    "filename": "account-a/1776427171_..._29960_sprite.jpg",
    "provider": "primary-provider",
    "uriExpiryTime": "24h"
  }
]

Response

A JSON map of filename → signed URL, embedded in the standard envelope as a string:

{
  "data": "{\"account-a/...mp4\":\"https://...\",\"account-a/..._thumbnail.jpg\":\"https://...\"}"
}

Note: data is a JSON-encoded string, not a nested object. Parse it twice: first the envelope, then data.

Example — get every generated link for a single media in one call:

curl -s -X POST "http://localhost:8085/api/storage/bulk" \
  -H "X-Kerberos-Storage-AccessKey: $VAULT_ACCESS_KEY" \
  -H "X-Kerberos-Storage-SecretAccessKey: $VAULT_SECRET" \
  -H "Content-Type: application/json" \
  -d '[
    {"filename":"account-a/1776427171_..._29960.mp4",            "provider":"primary-provider","uriExpiryTime":"24h"},
    {"filename":"account-a/1776427171_..._29960_thumbnail.jpg",  "provider":"primary-provider","uriExpiryTime":"24h"},
    {"filename":"account-a/1776427171_..._29960_sprite.jpg",     "provider":"primary-provider","uriExpiryTime":"24h"},
    {"filename":"account-a/1776427171_..._29960_redacted.mp4",   "provider":"primary-provider","uriExpiryTime":"24h"}
  ]' | jq -r '.data | fromjson'

A complete .http reference is shipped with the repository at vault/examples/get_signed_urls.http.

3. Two signing modes

The shape of the URLs returned by the endpoints above is controlled by the VAULT_SIGNING environment variable on the Vault deployment:

In both cases your integration code is identical — you call GET /api/storage or POST /api/storage/bulk and use whatever URL comes back. The next section is only relevant when VAULT_SIGNING=true.

Vault-signed URLs (VAULT_SIGNING=true)

In this mode the returned URL has the form:

{VAULT_PUBLIC_URL}/api/storage/signed
    ?a={account}
    &p={provider}
    &f={url-encoded filename}
    &e={expiry unix seconds}
    &s={HMAC token}

These public endpoints exist on every Vault instance:

The HMAC is computed with the secret in VAULT_URL_SIGNING_KEY and covers the account, provider, filename and expiry — so the URL cannot be tampered with and stops working after e.

Example

GET http://localhost:8085/api/storage/signed
  ?a=account-a
    &e=1777032108
  &f=account-a%2F1776427171_..._29960.mp4
  &p=primary-provider
  &s=<hmac-signature>

End-to-end: list every signed URL for a media

The recommended pattern when you need all assets for a recording (player + scrubber thumbnails + share link to the redacted version, etc.):

1. Start from the recording filename you already have, e.g. from a Hub pipeline event payload (payload.key).
2. Derive the asset filenames using the suffix convention (_thumbnail.jpg, _sprite.jpg, _redacted.mp4, …).
3. Call POST /api/storage/bulk once with the full list.
4. Use the URLs from the response directly — no further auth needed for the lifetime of uriExpiryTime.

MEDIA="account-a/1776427171_1-1_frontdoor_402-263-805-680_801_29960.mp4"
BASE="${MEDIA%.mp4}"

curl -s -X POST "$VAULT_URL/api/storage/bulk" \
  -H "X-Kerberos-Storage-AccessKey: $VAULT_ACCESS_KEY" \
  -H "X-Kerberos-Storage-SecretAccessKey: $VAULT_SECRET" \
  -H "Content-Type: application/json" \
  -d "[
    {\"filename\":\"${MEDIA}\",                  \"uriExpiryTime\":\"1h\"},
    {\"filename\":\"${BASE}_thumbnail.jpg\",     \"uriExpiryTime\":\"1h\"},
    {\"filename\":\"${BASE}_sprite.jpg\",        \"uriExpiryTime\":\"1h\"},
    {\"filename\":\"${BASE}_redacted.mp4\",      \"uriExpiryTime\":\"1h\"}
  ]" | jq -r '.data | fromjson'

Status codes