API Keys

API keys allow authenticated access without a JWT session. Bucket supports two key types: master keys for account-wide access, and container-scoped keys with path restrictions and granular permissions.

Key types

Master API Key

Account-wide access. Can read and write to any container owned by the account. Store securely; shown only once at creation.

Container API Key

Scoped to a single container. Supports path restrictions and a subset of permissions. Ideal for integrations or client-side apps.

Permissions

Assign permissions when creating a key. Supported values:

read — list directories and download files.
write — upload files and create directories.
edit — rename, move, or update file content.
delete — remove files and directories.

Create a master API key

Master keys authenticate against every container in the account. Use them for backend services or administrative tools.

typescript

const response = await fetch('https://bucket.dveloxsoft.com/api/api-keys/master', {
   method: 'POST',
   headers: {
     'Authorization': 'ApiKey <api_key>'
   }
 });

 const apiKey = await response.json();
 console.log('Master key:', apiKey.key);
 console.log('Permissions:', apiKey.permissions);

Create a container API key

Container keys limit access to a specific container. Use allowedPaths to restrict which folders the key can touch.

typescript

const response = await fetch('https://bucket.dveloxsoft.com/api/api-keys/new', {
   method: 'POST',
   headers: {
     'Content-Type': 'application/json',
     'Authorization': 'ApiKey <api_key>'
   },
   body: JSON.stringify({
     name: 'Mobile App',
     permissions: ['read', 'write'],
     containerId: 'container-uuid',
     allowedPaths: ['/public/*', '/uploads/**'],
     expireAt: '2027-01-01T00:00:00Z'
   })
 });

 const apiKey = await response.json();
 console.log('Container key:', apiKey.key);

Use an API key in requests

Send the key as an Authorization header or as a query parameter. Public containers still allow unauthenticated GET requests.

typescript

// Header style (recommended)
fetch('https://bucket.dveloxsoft.com/api/files/my-bucket/file.txt', {
   headers: {
     'Authorization': 'ApiKey <api_key>'
   }
 });

 // Query parameter style
 fetch('https://bucket.dveloxsoft.com/api/files/my-bucket/file.txt?apikey=<api_key>');

 // Public container read (no auth required)
 fetch('https://bucket.dveloxsoft.com/api/files/public-bucket/image.jpg');

List and revoke keys

Retrieve all keys for the authenticated user or revoke a specific key by ID.

typescript

// List all keys
const listResponse = await fetch('https://bucket.dveloxsoft.com/api/api-keys/all', {
   headers: {
     'Authorization': 'ApiKey <api_key>'
   }
 });
const keys = await listResponse.json();
console.log('Active keys:', keys);

// Revoke by ID
const deleteResponse = await fetch(`https://bucket.dveloxsoft.com/api/api-keys/${keyId}`, {
   method: 'DELETE',
   headers: {
     'Authorization': 'ApiKey <api_key>'
   }
 });

if (!deleteResponse.ok) {
   const error = await deleteResponse.json();
   throw new Error(error.message || 'Failed to revoke key');
 }

 console.log('Key revoked');