Authentication

Authenticate your requests using API keys or scoped tokens.

All requests to the Upload API require the Authorization header with a Bearer token.

API Key (Backend)

Full access. Keep secret.

Authorization: Bearer sk_...

Upload Token (Frontend)

Scoped access. Safe for clients.

Authorization: Bearer token_...

When to Use Each Method

Upload Tokens

Use for frontend applications and client-side code. Tokens are scoped to a specific file path and expire automatically.

Frontend applications (React, Vue, Angular)

Mobile apps where users upload files

Any client-side code in the browser

When restricting uploads to specific paths

API Keys

Use for backend servers and server-side scripts. Provides full access to upload to any path.

Backend servers (Node.js, Python, etc.)

Server-side scripts and automation

Uploading to multiple paths dynamically

Generating tokens for frontend use

Token Flow

1.Your backend generates a token for a specific file path

2.Frontend receives the token and uploads directly to the API

3.Token expires after use or time limit, keeping your API key safe

Token Flow Example

Complete examples for uploading from frontend or backend.

Choose your upload method. Each example clearly shows where the code runs.

BACKEND

Step 1

Generate Token on Your Server

Your backend creates a scoped token for a specific file path. Your API key stays secure on the server.

Node.js Backend (SDK)

import { UploadClient } from 'mediasaur';const client = new UploadClient({ apiKey: 'sk_...' });const { token } = await client.createToken({  bucket: 'my-bucket',  path: 'users/123/avatar.png',  expiresIn: 3600 // 1 hour});// Send token to frontend

Token sent to frontend

FRONTEND

Step 2

Upload File from Browser

Your frontend uses the token to upload directly. No API key exposed in client code.

React Frontend (SDK)

import { UploadClient } from 'mediasaur';const client = new UploadClient();const file = fileInput.files[0];const result = await client.upload({  file,  token, // Token from backend  path: 'users/123/avatar.png' // Must match token path});console.log('File uploaded:', result.url);

Why This Is Secure

API key never leaves your server

Token is scoped to a single file path

Token expires automatically (default: 1 hour)

Even if compromised, damage is limited to one upload

Generate Token

Create a scoped upload token for frontend use.

POSThttps://upload.mediasaur.com/token

Generates a signed JWT token that allows a client to upload a single file to a specific path.

Headers

Authorizationstringrequired

Must be a valid API Key (sk_...)

Body Parameters

bucketstringrequired

The target bucket name.

pathstringrequired

Exact path where the file will be uploaded.

expires_innumber

Token validity in seconds. Default: 3600

Upload File

Upload a file to storage.

POSThttps://upload.mediasaur.com/

Uploads a file using multipart/form-data. Supports both API Keys and Upload Tokens.

Headers

Authorizationstringrequired

API Key (sk_...) or Upload Token (token_...)

Form Data

fileFilerequired

The binary file content.

pathstringrequired

Destination path. Must match token path if using token auth.

bucketstring

Required ONLY when using API Key auth.