API reference for managing storage backends — Google Drive, Dropbox, AWS S3, and FTP/SFTP.

Storage API

Storage endpoints manage backends for encrypted document storage. All endpoints require authentication.

Base: /api/storages

GET /api/storages

List all storages for the authenticated Host.

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "storages": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "type": "gdrive",
      "name": "My Google Drive",
      "directory_path": "/BAP/wills",
      "is_connected": true,
      "last_verified_at": "2026-02-21T10:00:00Z",
      "created_at": "2026-02-20T09:00:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "type": "s3",
      "name": "My S3 Bucket",
      "directory_path": "/wills",
      "is_connected": true,
      "last_verified_at": "2026-02-21T11:00:00Z",
      "created_at": "2026-02-19T08:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
id	uuid	Unique identifier
type	string	Storage type (gdrive, dropbox, s3, sftp)
name	display name	Display name
directory_path	string	Folder path for will documents
is_connected	boolean	Whether currently connected
last_verified_at	timestamp	Last successful connection test
created_at	timestamp	Creation time

POST /api/storages

Create a new storage connection (S3 or SFTP).

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request: AWS S3

{
  "type": "s3",
  "name": "My S3 Bucket",
  "config": {
    "access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "bucket": "my-bap-wills",
    "region": "us-east-1"
  },
  "directory_path": "/wills"
}

Request: SFTP

{
  "type": "sftp",
  "name": "My SFTP Server",
  "config": {
    "host": "sftp.example.com",
    "port": 22,
    "username": "bap",
    "password": "secure_password"
  },
  "directory_path": "/home/bap/wills"
}

Request: SFTP with SSH Key

{
  "type": "sftp",
  "name": "My SFTP Server",
  "config": {
    "host": "sftp.example.com",
    "port": 22,
    "username": "bap",
    "ssh_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----"
  },
  "directory_path": "/home/bap/wills"
}

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "s3",
  "name": "My S3 Bucket",
  "directory_path": "/wills",
  "is_connected": true,
  "last_verified_at": "2026-02-21T10:00:00Z",
  "created_at": "2026-02-21T10:00:00Z"
}

Config Schemas

Type	Required Config Fields
s3	access_key_id, secret_access_key, bucket, region
sftp	host, port, username, password OR ssh_key
gdrive, dropbox	Use OAuth flow instead

POST /api/storages/connect

Initiate OAuth flow for Google Drive or Dropbox.

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request: Google Drive

{
  "type": "gdrive"
}

Request: Dropbox

{
  "type": "dropbox"
}

Request: OneDrive

{
  "type": "onedrive"
}

Response (200 OK)

{
  "redirect_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&scope=...&state=...",
  "state": "random-csrf-state"
}

OAuth Flow

Client receives redirect_url
Redirects user to provider
User authorizes BAP
Provider redirects to /api/storages/oauth/callback
Server exchanges code for tokens
Storage is created

GET /api/storages/oauth/callback

OAuth callback handler (called by provider redirect).

Query Parameters

Parameter	Description
code	Authorization code from provider
state	CSRF state token

Response

302 redirect to frontend with success/failure indicator:

https://yourdomain.com/dashboard?storage=success
https://yourdomain.com/dashboard?storage=error

GET /api/storages/:id/browse

Browse files and directories in storage.

Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter	Type	Default	Description
path	string	/	Directory path to browse
page_token	string	-	Pagination token

Response (200 OK)

{
  "items": [
    {
      "name": "wills",
      "type": "directory",
      "path": "/wills",
      "size_bytes": null,
      "modified_at": "2026-02-20T00:00:00Z"
    },
    {
      "name": "document.pdf.enc",
      "type": "file",
      "path": "/wills/document.pdf.enc",
      "size_bytes": 1048576,
      "modified_at": "2026-02-21T00:00:00Z"
    }
  ],
  "next_page_token": null
}

DELETE /api/storages/:id

Disconnect and remove a storage.

Headers

Authorization: Bearer <access_token>

Response (204 No Content)

No body returned.

Errors

409 — Storage has active will documents

Rate Limits

Endpoint	Limit	Window
GET /storages	100 requests	1 minute
POST /storages	10 requests	1 hour
GET /storages/:id/browse	50 requests	1 minute

Example: Create S3 Storage

curl -X POST "https://api.example.com/api/storages" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "s3",
    "name": "My S3 Bucket",
    "config": {
      "access_key_id": "AKIAIOSFODNN7EXAMPLE",
      "secret_access_key": "example",
      "bucket": "my-bap-wills",
      "region": "us-east-1"
    },
    "directory_path": "/wills"
  }'

Example: Browse Storage

curl -X GET "https://api.example.com/api/storages/550e8400-e29b-41d4-a716-446655440001/browse?path=/wills" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Connectors API — Notification channels
Will API — Document management

Storage API

On this page