Access URLs

How an object is read depends on its bucket. A public bucket has one stable URL per object that anyone can fetch; a private bucket answers only a signed URL you mint per object, with an expiry attached.

Asking for a URL

One call covers both cases, and the response tells you which one you got. The example runs inside a deployed Function, where the client needs no configuration; see OIDC federation for the credentials the platform injects.

import { GigadriveClient } from '@gigadrive/sdk';

const client = new GigadriveClient();

const object = await client.storage.objects.getByKey('user-uploads', 'avatars/user-123.png');
if (!object) throw new Error('No such object');

const access = await client.storage.objects.getAccessUrl('user-uploads', object.id, {
  expiresInSeconds: 3600,
});

console.log(access.accessType, access.url, access.expiresAt);

{
  "accessType": "signed",
  "url": "https://user-uploads-k7qm4ztb.private.gigadriveuserstorage.com/avatars/user-123.png?bucket_host=user-uploads-k7qm4ztb.private.gigadriveuserstorage.com&token=HS256-Vd8n...&expires=1786629600",
  "expiresAt": "2026-08-13T14:00:00.000Z"
}

accessType is public for a public bucket, in which case expiresAt is null and the URL never changes. The call needs the network:storage_objects:read scope.

Public URLs

A public object is served from the bucket's CDN hostname, which is its slug plus the public label:

https://user-uploads-k7qm4ztb.public.gigadriveuserstorage.com/avatars/user-123.png

Each path segment is percent encoded and the slashes are kept, so a key with a space or an umlaut still produces a valid URL. You do not have to call the API to build it: the same URL comes back as upload.publicObjectUrl when you create an upload session, and the slug and hostname are on the bucket itself. Store it and skip the round trip.

Signed URLs

A signed URL carries a token and an expires parameter and stops working the moment it expires. Ask for one per object, per viewer, at the moment you render the page.

A value outside that range is refused with a 400, so expiresInSeconds=30 and expiresInSeconds=604800 both fail validation instead of being rounded into range. The API sends the response with Cache-Control: no-store. Treat the URL the same way: do not put it in a shared cache or in a page that a CDN keeps.

Choosing between them

Put files that are meant to be seen by everyone in a public bucket: avatars on a public profile, marketing images, anything you would otherwise ship in the repository. Use a private bucket the moment a file belongs to one account, because a public URL is a permanent one, and the only way to withdraw it is to delete the object.

Visibility is chosen when the bucket is created, and no console control, REST route or SDK method changes it afterwards. Decide before you upload. See Buckets.