Signed URLs

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

import requests

url = "https://api.example.com/v1/files/:id/signed-url"

payload = { "expires_in": 123 }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({expires_in: 123})
};

fetch('https://api.example.com/v1/files/:id/signed-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/files/:id/signed-url",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'expires_in' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/files/:id/signed-url"

	payload := strings.NewReader("{\n  \"expires_in\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/files/:id/signed-url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expires_in\": 123\n}"

response = http.request(request)
puts response.read_body

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

POST

files

:id

signed-url

Signed URLs

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

import requests

url = "https://api.example.com/v1/files/:id/signed-url"

payload = { "expires_in": 123 }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({expires_in: 123})
};

fetch('https://api.example.com/v1/files/:id/signed-url', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/files/:id/signed-url",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'expires_in' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/files/:id/signed-url"

	payload := strings.NewReader("{\n  \"expires_in\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/files/:id/signed-url")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expires_in\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "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

string

required

The file ID. Example: f_abc123xyz

Body Parameters

integer

required

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

Response

string

required

Signed URL that grants temporary access to the file.

string

required

ISO 8601 timestamp when the URL expires.

Examples

Generate a 1-Hour URL

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}'

const response = await fetch(
  'https://api.stashfyle.com/v1/files/f_abc123xyz/signed-url',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_xxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ expires_in: 3600 })
  }
);

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

response = requests.post(
    'https://api.stashfyle.com/v1/files/f_abc123xyz/signed-url',
    headers={
        'Authorization': 'Bearer sk_live_xxx',
        'Content-Type': 'application/json'
    },
    json={'expires_in': 3600}
)

data = response.json()
signed_url = data['url']

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.

Overview

Uploads

Files

Signed URLs

Account

Signed URLs

Request

Path Parameters

Body Parameters

Response

Examples

Generate a 1-Hour URL

Common Expiration Times

Use Cases

Secure File Downloads

Image Previews

Errors

Best Practices

​Request

​Path Parameters

​Body Parameters

​Response

​Examples

​Generate a 1-Hour URL

​Common Expiration Times

​Use Cases

​Secure File Downloads

​Image Previews

​Errors

​Best Practices

Request

Path Parameters

Body Parameters

Response

Examples

Generate a 1-Hour URL

Common Expiration Times

Use Cases

Secure File Downloads

Image Previews

Errors

Best Practices