BucktDocs

Authentication

Every Buckt API request is authenticated with an API key passed as a Bearer token in the Authorization header. Each key carries a set of permission scopes that gate which endpoints it can call, and can optionally be scoped to specific buckets.

Sending requests

import { Buckt } from "@buckt/sdk";

const client = new Buckt({ apiKey: process.env.BUCKT_API_KEY });
const { data } = await client.buckets.list();

API keys start with bkt_. Mint one from the dashboard or via Create key.

Errors

Authentication and authorization failures use two status codes:

  • 401 Unauthorized — the request had no Authorization header, the header didn't start with bkt_, the key doesn't exist, or it's past its expiresAt.
  • 403 Forbidden — the key is valid but doesn't carry a permission scope the endpoint requires.
401 Unauthorized
{
  "data": null,
  "error": { "message": "Invalid API key" },
  "meta": null
}
403 Forbidden
{
  "data": null,
  "error": { "message": "Insufficient permissions" },
  "meta": null
}

Permissions

Every endpoint shows its required scope in the endpoint header — e.g. POST /v1/buckets requires buckets:write. A key needs every required scope for the request to succeed.

Available scopes

  • buckets:read — Read bucket configuration and usage.
  • buckets:write — Create and update buckets, retry failed provisioning, and import S3 buckets from a connected AWS account.
  • buckets:delete — Delete buckets.
  • files:read — Read file metadata and list files.
  • files:write — Upload files.
  • files:delete — Delete files.
  • keys:read — Read API key metadata.
  • keys:write — Create and revoke API keys.
  • aws-accounts:read — Read connected AWS accounts and list S3 buckets.
  • aws-accounts:write — Connect, update, and validate AWS accounts.
  • aws-accounts:delete — Disconnect AWS accounts.

Bucket-scoped keys

By default a key works against every bucket in the organization. Set bucketIds on Create key to restrict it — only the listed buckets accept reads, uploads, lists, and deletes from that key. Calls against other buckets return 404 Bucket not found so the key can't even confirm whether other buckets exist.

Best practices

  • Scope minimally. A frontend that only uploads images needs files:write plus a single bucketIds entry — not buckets:* across the org.
  • Rotate before deleting. Mint the replacement key, deploy it, then call Delete key on the old one. There's no grace period on delete — revocation is immediate.
  • Set expiresAt on keys handed to short-lived environments: CI builds, contractor access, ephemeral previews.
  • Watch lastUsedAt via List keys to spot keys that haven't been used in a while — strong candidates for revocation.