Access control & keys

Named access keys authenticate the S3 API. Whether an object is readable without one depends on the bucket, and on whether you signed a link for it.

4 min read

Access keys

S3 clients authenticate with an access key: an Access Key ID and a Secret Access Key. Your workspace can hold as many as you like, each with a name, listed under Object storage → Access keys and Settings → Storage keys (the same list in both places).

Every key reaches every bucket in the workspace. Give each app or job its own key, named after it, so you can revoke one without touching the others.

They authenticate nothing else. Email, deploys and the platform API use a scoped API key, which is a different credential with a different lifetime.

One key covers every region. Storing in a second region does not issue a second key: the same key works against each region's endpoint, so only the endpoint and region in your client config change. A bucket shows the endpoint and region to pair them with on its own page.

Creating a key

Owners and admins can create keys. Choose Create access key, give it a name, and the next screen shows the Access Key ID and the secret with the endpoint.

The secret is shown once, on that screen. Copy it somewhere safe before you close it — it can't be shown again. If you lose it, create a new key and revoke the old one.

Treat the secret like a database password:

Keep it in environment variables, not in the repository.
Do not ship it to a browser or a mobile app. Anything a client can read, a user can extract. Sign a URL instead.
Revoke it if it may have been exposed.

Revoking a key

Revoke on a key, then type its name to confirm. Apps using that key lose access to your buckets straight away, in every region. Revoking can't be undone. Your buckets and files are not affected, and other keys keep working.

To replace a key without downtime:

Create a new key.
Update the variables on every service that used the old one.
Redeploy those services so they pick up the new values.
Revoke the old key.

Revoking every key doesn't lock you out: the dashboard still opens your buckets, so you can create a new key at any time.

Public and private buckets

Access is set per bucket, on its Permissions tab.

Private means objects require credentials, or a signed link. This is the default, and the right setting for anything belonging to a user.

Public read means every object in the bucket is readable by anyone with its URL, with no credentials. Suitable for assets that are already public.

Public read is not per object. Turning it on exposes everything in the bucket, including anything uploaded there earlier. Keep public assets in a bucket that has never held anything private.

Signed links

A signed URL grants time-limited access to one object in a private bucket. That is how you let a user download their own invoice without making the bucket public:

A short-lived download link

import { GetObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { s3 } from './storage.js';

export const downloadUrl = (key) =>
  getSignedUrl(s3, new GetObjectCommand({ Bucket: 'my-bucket', Key: key }), {
    expiresIn: 300,
  });

Two rules:

Authorise before you sign. The signature proves the link came from you, not that the requester is allowed the file. Check ownership first.
Keep expiry short. A signed URL works for anyone holding it until it expires, so minutes rather than days.

CORS for browser uploads

A browser uploading straight to a bucket makes a cross-origin request, which the bucket must allow. Without it the browser blocks the preflight and the upload fails before any bytes are sent. That usually shows up as a network error with nothing in your server logs, because the request never reached your server.

A new bucket starts with no CORS rules, so no website can call it until you add one. On the bucket's Permissions tab, Add origin lets a site read (GET, HEAD), and your own apps' addresses are suggested there. For uploads, use Edit as JSON to allow:

your site's origin,
the methods you use (PUT for uploads, GET for reads),
the headers your client sends, such as Content-Type.

When you upload or download from the dashboard, Naijacloud adds one rule for the dashboard's own address so that page can do it. It is labelled Naijacloud dashboard on the tab and is not an access grant: every request still needs a signed link or an access key.

List your real origins explicitly, including the local one you develop against. A wildcard origin on a bucket that accepts uploads lets any site on the internet use your signed URLs.

Lifecycle rules

For objects that should not live forever, the bucket's Management tab takes rules such as expiring anything under a tmp/ prefix after a number of days. That keeps temporary uploads from accumulating without a cleanup job.

Next steps

Team & rolesWho in your workspace can see and change what.