Authentication

Every Upload API request identifies the project with the public key, sent as the UPLOADCARE_PUB_KEY parameter or pub_key where the endpoint says so.

Signed access

A project with Signed Uploads turned on additionally requires a credential generated on your backend with the project secret key. You create secret keys yourself in the API keys section of your Dashboard. A project can have more than one.

There are two credential schemes:

• Token, a JSON Web Token in the Authorization header. It can restrict which endpoints the client may call and how many operations it may spend.
• Signature (legacy), the signature and expire request parameters. It allows every upload endpoint until it expires. AI image endpoints accept tokens only. The scheme stays supported, but use tokens for new integrations.

Credentials are checked only when the project has Signed Uploads or Signed AI image generation turned on. The signed uploads guide explains how to enable them and which credential to choose.

Token

A token is a JSON Web Token (RFC 7519) sent in the Authorization header with the Bearer scheme:

Authorization: Bearer <jwt>

Signing

The token MUST be signed with HS256. The signing key is the SHA-256 digest of the project secret key, as raw 32 bytes rather than their hex representation. Any of the project’s secret keys works.

Hash the secret key as the characters you copied from the dashboard, not as the bytes that hex string decodes to. Both that and signing with the digest’s hex form produce Invalid token. Reason: signature does not match, which is the most common way a hand-rolled token fails.

Claims

Standard claims sit at the root of the payload. Everything Uploadcare interprets sits under the uc claim.

nbf, if present, is enforced: a token used before that time is rejected with AccessTokenInvalidError. Other standard claims are ignored. Keys under uc other than the ones in that table are not allowed: such a token is rejected.

Payload example:

{
  "iat": 1700000000,
  "exp": 1700003600,
  "sub": "example_user_01",
  "uc": {
    "restrictions": {
      "scope": ["/base/", "/multipart/*"],
      "limits": { "operations": 10 }
    }
  }
}

Scope and limits

Each signed endpoint has a scope path. A scope item matches a path exactly, or as a prefix when it ends with /*. A bare /* matches every endpoint. The list holds from 1 to 16 items, each up to 64 characters and starting with /.

The AI image endpoints are checked only when Signed AI image generation is on, and they accept auth tokens only, not signatures. Polling a generation’s status is not checked.

The operations counter lives as long as the token. A request that would exceed the limit is refused. A request refused before any file is saved or any job is started consumes nothing. Once a direct upload saves its first file, the whole request’s operations are spent, even if a later file in the same request fails. A multipart upload that is started but never completed still consumes its operation.

One counter per token

Uploadcare keys the counter by the token itself, not by its claims. Two tokens minted in the same second with the same claims are byte-identical, so they share one counter, and one user can spend another’s limit. If you set operations, add a sub (for example, the user ID) or a jti (a random ID) so every token is unique. Uploadcare doesn’t read either claim.

Generate a token

Use the Uploadcare Node SDK, or any JWT library that supports HS256. The samples set operations, so they also set sub to give each token its own counter:

    // npm install @uploadcare/signed-uploads
    import { randomUUID } from 'node:crypto';
    import { generateAuthToken } from '@uploadcare/signed-uploads';
    const token = generateAuthToken('YOUR_SECRET_KEY', {
      lifetime: 30 * 60 * 1000, // 30 minutes, in milliseconds
      // `sub` and `jti` keep this token's operation count separate.
      subject: 'user_123',
      tokenId: randomUUID(),
      scope: ['/base/'],
      operations: 5,
    });

Upload example

curl -H "Authorization: Bearer YOUR_TOKEN" \
     -F "UPLOADCARE_PUB_KEY=YOUR_PUBLIC_KEY" \
     -F "file=@image.jpg" \
     "https://upload.uploadcare.com/base/"

{
  "file": "c0d776d4-8c8e-47df-9e92-03b68b99c2ba"
}

Errors

With Accept: application/json (exactly) or the jsonerrors=1 query parameter, errors come back as HTTP 200 with the real status in status_code. The one exception is DerivativeQuotaExceededError, which keeps its 429. Upload Client sends jsonerrors=1 and reads it. Otherwise, the HTTP status is the real one. Either way, branch on error_code.

On uploads, the JavaScript libraries handle two of these for you: given a way to fetch a token, they answer AccessTokenExpiredError and OperationsLimitExceededError by dropping the refused token and retrying the request once. The AI image endpoints are not retried. See when a credential is refused.

Signature

The signature and expire parameters are sent together with the request, either in the query string or as form fields.

Any of the project’s secret keys works.

Generate a signature

// Option 1: by expiration timestamp (milliseconds since epoch)
import { generateSecureSignature } from '@uploadcare/signed-uploads'
const { secureSignature, secureExpire } = generateSecureSignature('YOUR_SECRET_KEY', {
  expire: Date.now() + 60 * 30 * 1000 // expire in 30 minutes
})

// Option 2: by expiration date
import { generateSecureSignature } from '@uploadcare/signed-uploads'
const { secureSignature, secureExpire } = generateSecureSignature('YOUR_SECRET_KEY', {
  expire: new Date("2099-01-01") // expire on 2099-01-01
})

// Option 3: by lifetime
import { generateSecureSignature } from '@uploadcare/signed-uploads'
const { secureSignature, secureExpire } = generateSecureSignature('YOUR_SECRET_KEY', {
  lifetime: 60 * 30 * 1000 // expire in 30 minutes
})

Upload example

curl -F "UPLOADCARE_PUB_KEY=YOUR_PUBLIC_KEY" \
     -F "signature=YOUR_SIGNATURE" \
     -F "expire=YOUR_EXPIRE" \
     -F "file=@image.jpg" \
     "https://upload.uploadcare.com/base/"

Errors

For the complete list of Upload API errors, see Errors.