Uploads

Two things can be uploaded: a user’s avatar and an organization’s logo. Both work the same way, and neither sends bytes through the API.

When the server has no storage configured, both routes answer 501 uploads_unavailable and GET /v1/session reports uploads_available: false — read that flag before showing an upload button, rather than hitting the 501 mid-flow.

The flow

Ask for a signed URL

curl -s $API/v1/account/avatar/upload-url \
  -H "Authorization: Bearer $UK_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{ "content_type": "image/png", "size_bytes": 184320 }'

{
  "upload_url": "https://bucket.example.com/avatars/…?X-Amz-Signature=…",
  "headers": { "Content-Type": "image/png" },
  "public_url": "https://cdn.example.com/avatars/…"
}

PUT the file straight to the bucket

curl -X PUT "$UPLOAD_URL" \
  -H 'Content-Type: image/png' \
  --data-binary @avatar.png

Send exactly the headers that came back — they are part of the signature.

Save the public URL

curl -s -X PATCH $API/v1/account \
  -H "Authorization: Bearer $UK_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{ "avatar_url": "https://cdn.example.com/avatars/…" }'

Saving is a separate call on purpose. The upload can fail halfway, and a profile pointing at a half-written object would be worse than one still pointing at the old image.

The organization logo

Identical, with two differences: it needs organization:update, and the URL is saved with PATCH /v1/organization.

curl -s $API/v1/organization/logo/upload-url \
  -H "Authorization: Bearer $UK_SESSION" \
  -H "X-Organization-Id: org_4b1e…" \
  -H 'Content-Type: application/json' \
  -d '{ "content_type": "image/webp", "size_bytes": 24576 }'

What is allowed


Types	`image/jpeg`, `image/png`, `image/webp`, `image/gif`
Size	1 byte to 5 MiB

An allowlist, not a blocklist — deliberately. These files are served back from a public host, and text/html among them would be a stored-XSS vector on that host.

Response	Cause
`400 unsupported_type`	Not one of the four image types
`400 invalid_size`	`size_bytes` is 0, negative, or over 5 MiB
`501 uploads_unavailable`	File storage is unavailable on the server

Content type and size are part of the signature, so the bucket enforces them. The check on the API side is there to give you a readable error, not to be the enforcement.

Replacing an image

Every upload gets a random object key, so replacing an image never overwrites the old object. A URL cached in a CDN or an email cannot start serving somebody else’s picture. The old object is left behind. Pruning is a housekeeping job, not part of the request.

Doing it from the browser

The three steps work the same from client code. A presigned URL is short-lived and bound to one object, one content type and one size, so handing it to a browser gives away nothing reusable.

const signed = await fetch("https://api.userkit.dev/v1/account/avatar/upload-url", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${sessionToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ content_type: file.type, size_bytes: file.size }),
}).then((r) => r.json());

// Straight to the bucket. This request carries no credential of ours.
await fetch(signed.upload_url, {
  method: "PUT",
  headers: signed.headers,
  body: file,
});

await fetch("https://api.userkit.dev/v1/account", {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${sessionToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ avatar_url: signed.public_url }),
});

A session token in browser code is only as safe as where you keep it. If your app has a server, the shape worth copying is to sign the first and third calls there and let the browser do only the PUT — the bucket upload is the only one of the three that needs to happen from the device holding the file.

Get started

Core concepts

Customer authentication

Guides

The flow

The organization logo

What is allowed

Replacing an image

Doing it from the browser

​The flow

​The organization logo

​What is allowed

​Replacing an image

​Doing it from the browser

The flow

The organization logo

What is allowed

Replacing an image

Doing it from the browser