Signed URLs

Generate temporary access URLs for private files.

POST /v1/files/:id/signed-url

Signed URLs

cURL

curl --request POST \
  --url https://api.example.com/v1/files/:id/signed-url \
  --header 'Content-Type: application/json' \
  --data '
{
  "expires_in": 123
}
'

200

{
  "url": "<string>",
  "expires_at": "<string>"
}

Generate a signed URL to access a private file. Signed URLs expire after the specified duration.

This endpoint requires a secret key (sk_). Public keys cannot generate signed URLs.

Request

Path Parameters

id · string · required

The file ID. Example: f_abc123xyz

Body Parameters

expires_in · integer · required

URL validity in seconds. Max: 604800 (7 days).

Response

url · string · required

Signed URL that grants temporary access to the file.

expires_at · string · required

ISO 8601 timestamp when the URL expires.

Examples

Generate a 1-Hour URL

curl

curl -X POST https://api.stashfyle.com/v1/files/f_abc123xyz/signed-url \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 3600}'

Response

{
  "url": "https://cdn.stashfyle.com/live/user_123/f_abc123xyz/document.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...&X-Amz-Signature=...",
  "expires_at": "2024-01-15T11:30:00Z"
}

Common Expiration Times

Duration	Seconds
15 minutes	900
1 hour	3600
24 hours	86400
7 days	604800

Use Cases

Secure File Downloads

// Generate a short-lived URL for download
async function getSecureDownloadUrl(fileId) {
  const response = await fetch(
    `https://api.stashfyle.com/v1/files/${fileId}/signed-url`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.STASHFYLE_SECRET_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ expires_in: 300 }) // 5 minutes
    }
  );

  const { url } = await response.json();
  return url;
}

// Use in your API endpoint
app.get('/download/:fileId', async (req, res) => {
  const downloadUrl = await getSecureDownloadUrl(req.params.fileId);
  res.redirect(downloadUrl);
});

Image Previews

// Generate URLs for private image thumbnails
async function getImagePreviewUrl(fileId) {
  const response = await fetch(
    `https://api.stashfyle.com/v1/files/${fileId}/signed-url`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ expires_in: 3600 }) // 1 hour
    }
  );

  return response.json();
}

Errors

Code	Status	Description
unauthorized	401	Invalid or missing API key
forbidden	403	Public key used (requires secret key)
not_found	404	File not found
bad_request	400	Invalid expires_in value
rate_limit_exceeded	429	Too many requests

Best Practices

Use short expiration times

Generate URLs with the minimum required validity. This limits exposure if a URL is leaked.

Generate on-demand

Don’t store signed URLs. Generate them when needed—they’re fast to create.

Don't expose in client-side code

Generate signed URLs on your server and pass them to the client. Never expose your secret key.