Skip to main content

​
Overview

The delegate-upload endpoint allows your Platform to generate secure, short-lived JWT tokens for your merchants’ frontend upload widgets (Uppy). This enables direct browser-to-storage uploads while maintaining proper attribution and billing.
Delegated tokens expire after 5 minutes by default. Request a fresh token for each upload session.

​
Endpoint

POST /v1/auth/delegate-upload

​
Authentication

This endpoint requires your Platform API key in the Authorization header: 
Authorization: Bearer your_platform_api_key
Never expose your Platform API key in frontend code. The delegate-upload call must be made from your backend.

​
Request Body

FieldTypeRequiredDescription
merchant_idstringYesYour internal identifier for the merchant

​
Example Request

curl -X POST https://api.superseeded.ai/v1/auth/delegate-upload \
  -H "Authorization: Bearer your_platform_api_key" \
  -H "Content-Type: application/json" \
  -d '{"merchant_id": "merchant_123"}'

​
Response

​
token
string
required
Short-lived JWT token for Uppy authentication
​
expires_at
string
required
ISO 8601 timestamp when the token expires

​
Example Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-01-20T12:05:00Z"
}

​
JWT Token Claims

The generated token contains claims that are used for attribution and billing:
ClaimDescription
subThe merchant_id you provided
api_key_idYour Platform’s API key identifier
scopeToken scope (e.g., upload)
entity_typeEntity type identifier
expToken expiration timestamp
iatToken issued-at timestamp
The same delegation token is used for both the TUS upload and the subsequent processing request. This simplifies your integration since one token handles the entire flow.

​
Usage Flow

1

Merchant Initiates Upload

Your merchant clicks an upload button in your frontend application.
2

Request Delegation Token

Your backend calls the delegate-upload endpoint with the merchant’s ID.
// Your backend
const { token, expires_at } = await getDelegationToken(merchantId);
3

Pass Token to Frontend

Send the JWT token to your frontend Uppy widget.
// Return to frontend
res.json({ uploadToken: token });
4

Configure Uppy

Your frontend configures Uppy with the delegation token.
const uppy = new Uppy()
  .use(Tus, {
    endpoint: 'https://tus.superseeded.com/files/',
    headers: {
      Authorization: `Bearer ${uploadToken}`
    }
  });
5

Direct Upload

Uppy uploads the file directly to our TUS server using the token for authentication. After the upload completes, Uppy returns the file URL.
6

Call Processing Endpoint

Your frontend calls the verify-pot-sizes endpoint with the same delegation token and the uploaded file URL.
const response = await fetch('https://api.superseeded.ai/v1/verify/pot-sizes', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${uploadToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    file_url: uploadResult.uploadURL
  })
});
const { results } = await response.json();
7

Receive Enriched Data

The API fetches the file internally, processes it, bills the merchant (from the JWT), and returns enriched data directly in the response. See Verify Pot Sizes from Upload for the full response schema.

​
Error Responses

StatusErrorDescription
401unauthorizedInvalid or missing API key
400invalid_requestMissing merchant_id in request body
429rate_limitedToo many token requests

​
Best Practices

Don’t pre-fetch tokens. Request a fresh token when the user is ready to upload to ensure it doesn’t expire mid-upload.
If an upload fails due to token expiration, request a new token and retry. Uppy supports automatic retry with updated headers.
Use your internal user/merchant ID consistently. This ID is used for billing aggregation and usage tracking.