Claves API

Las claves API permiten el acceso autenticado sin una sesión JWT. Bucket admite dos tipos de claves: claves maestras para acceso a toda la cuenta, y claves por contenedor con restricciones de ruta y permisos granulares.

Tipos de claves

Clave API maestra

Acceso a toda la cuenta. Puede leer y escribir en cualquier contenedor propiedad de la cuenta. Almacénala de forma segura; solo se muestra una vez al crearla.

Clave API por contenedor

Limitada a un solo contenedor. Admite restricciones de ruta y un subconjunto de permisos. Ideal para integraciones o aplicaciones del lado del cliente.

Permisos

Asigna permisos al crear una clave. Valores admitidos:

read — lista directorios y descarga archivos.
write — sube archivos y crea directorios.
edit — renombra, mueve o actualiza el contenido de archivos.
delete — elimina archivos y directorios.

Crear una clave API maestra

Las claves maestras se autentican contra todos los contenedores de la cuenta. Úsalas para servicios backend o herramientas administrativas.

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);

Crear una clave API por contenedor

Las claves por contenedor limitan el acceso a un contenedor específico. Usa allowedPaths para restringir las carpetas que la clave puede modificar.

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);

Usar una clave API en solicitudes

Envía la clave como encabezado Authorization o como parámetro de consulta. Los contenedores públicos aún permiten solicitudes GET sin autenticación.

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');

Listar y revocar claves

Recupera todas las claves del usuario autenticado o revoca una clave específica por 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');