# Signed Uploads

[View original](https://ittybit.com/guides/signed-uploads)

## How it works

A signed upload url is includes a valid signature which will grant access to your project for a limited time.

Once you have the signed url, you make a `PUT` request with the file in the request body.

When the upload completes, ittybit will return a [File object](/docs/files) in the response.

***

## Signed urls

A signed url looks like this:

`https://you.ittybit.net/image.png?expiry=1765432100&signature=1234abcd5678efgh9012`

* `domain`: your project's delivery domain (see [Domains](/docs/domains) for info on setting up custom domains) e.g. `https://you.ittybit.net`.

* `filename`: the name of the file you want to upload e.g. `image.png`.

* `folder`: (optional) include folders in your pathname to organise your files e.g. `nested/folders/image.png`.

* `expiry`: a unix timestamp for some time in the near future. The url will stop working after this time e.g. `expiry=1765432100`.

* `signature`: a base64 encoded string. The string that is encoded is the `domain`, `folder`, `filename`, and `expiry` values, signed with your project's API key.

***

## 1. Get a signed url

To get a valid signed url, you will need to make a request to your server, get the url, and return it to your client.

If you're using a REST API for data fetching (could be powered by Express/Node, Laravel, Rails, or similar) then this would probably be an API route.

```js
// Example fetch request to your API server
const response = await fetch('https://your.api.com/upload-url', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    // Add your authentication headers
  },
  body: JSON.stringify({
    filename: 'image.png',
  }),
});
const { url } = await response.json();
```

<Callout>
  <Icon icon="info" />

  Next.js, SvelteKit, and similar frontend frameworks can use server actions to generate or fetch a signed url directly.
</Callout>

### Generate a signature yourself

\[Guide coming soon!]

### Use the `/signatures` endpoint

If you can't generate a signature yourself, then you can create a signed url using our [signatures API endpoint](/api/signatures).

***

## 2. Upload the file

Once you have the signed url, you can upload the file to ittybit.

```js
const response = await fetch(url, {
  method: 'PUT',
  body: file,
});
```

***

## 3. Handle the response

When your upload completes, ittybit will return a [File object](/docs/files) in the response.

```js
const { meta, data, error, links } = await response.json();
```

* `meta`: contains information about the request.

* `data`: contains the file object.

* `error`: will only be present if the upload failed.

* `links`: contains a link to the file object.

***

## File object

```json
{
  "id": "file_abcdefgh1234",
  "kind": "image",
  "type": "image/png",
  "width": 3000,
  "height": 2000,
  "filesize": 12345678,
  "url": "https://you.ittybit.net/image.png",
  "created": "2025-01-01T01:23:45Z",
  "updated": "2025-01-01T01:23:45Z"
}
```

You can persist this info to your database, and use it to serve the file to your users.

***

[^1]: You get a free `*.ittybit.net` domain when you create a project. You can also add [Custom Domains](/docs/domains) in your project settings.