b0esche_cloud/docs/API.md

b0esche.cloud API Reference

Base URL: https://go.b0esche.cloud

Authentication

All authenticated endpoints require a JWT token in the Authorization header:

Authorization: Bearer <token>

---

Health Check

GET /health

Check if the API is running.

Response:

{
  "status": "ok",
  "timestamp": "2026-01-13T19:00:00Z"
}

---

Authentication Endpoints

Passkey Registration

POST /auth/passkey/register/start

Start passkey registration for a new user.

Request Body:

{
  "username": "johndoe"
}

Response:

{
  "publicKey": {
    "challenge": "base64-encoded-challenge",
    "rp": {
      "name": "b0esche.cloud",
      "id": "www.b0esche.cloud"
    },
    "user": {
      "id": "base64-user-id",
      "name": "johndoe",
      "displayName": "johndoe"
    },
    "pubKeyCredParams": [...],
    "timeout": 300000,
    "attestation": "none"
  }
}

POST /auth/passkey/register/verify

Complete passkey registration.

Request Body:

{
  "username": "johndoe",
  "credential": {
    "id": "credential-id",
    "rawId": "base64-raw-id",
    "type": "public-key",
    "response": {
      "clientDataJSON": "base64-client-data",
      "attestationObject": "base64-attestation"
    }
  }
}

Response:

{
  "user": {
    "id": "uuid",
    "username": "johndoe"
  },
  "token": "jwt-token"
}

Passkey Login

POST /auth/passkey/login/start

Start passkey authentication.

Request Body:

{
  "username": "johndoe"
}

Response:

{
  "publicKey": {
    "challenge": "base64-challenge",
    "timeout": 300000,
    "rpId": "www.b0esche.cloud",
    "allowCredentials": [...]
  }
}

POST /auth/passkey/login/verify

Complete passkey authentication.

Request Body:

{
  "username": "johndoe",
  "credential": {
    "id": "credential-id",
    "rawId": "base64-raw-id",
    "type": "public-key",
    "response": {
      "clientDataJSON": "base64-client-data",
      "authenticatorData": "base64-auth-data",
      "signature": "base64-signature"
    }
  }
}

Response:

{
  "user": {
    "id": "uuid",
    "username": "johndoe",
    "role": "user"
  },
  "token": "jwt-token"
}

Device Management

GET /auth/passkey/devices

List user's registered passkeys.

Response:

{
  "devices": [
    {
      "id": "uuid",
      "credentialId": "credential-id",
      "deviceLabel": "MacBook Pro",
      "createdAt": "2026-01-01T00:00:00Z",
      "lastUsedAt": "2026-01-13T19:00:00Z",
      "backupEligible": true
    }
  ]
}

POST /auth/passkey/devices/add

Add a new passkey to existing account.

DELETE /auth/passkey/devices/{passkeyId}

Remove a passkey from account.

Recovery Codes

POST /auth/recovery/codes/generate

Generate new recovery codes (invalidates old ones).

Response:

{
  "codes": [
    "XXXX-XXXX-XXXX",
    "YYYY-YYYY-YYYY",
    ...
  ],
  "expiresAt": "2027-01-13T00:00:00Z"
}

POST /auth/recovery/codes/use

Use a recovery code to authenticate.

Request Body:

{
  "username": "johndoe",
  "code": "XXXX-XXXX-XXXX"
}

Password (Optional Fallback)

POST /auth/password/add

Add password to account.

Request Body:

{
  "password": "secure-password"
}

DELETE /auth/password/remove

Remove password from account.

---

User Endpoints

GET /api/me

Get current user profile.

Response:

{
  "id": "uuid",
  "username": "johndoe",
  "email": "john@example.com",
  "displayName": "John Doe",
  "role": "user",
  "createdAt": "2026-01-01T00:00:00Z"
}

PATCH /api/me

Update user profile.

Request Body:

{
  "displayName": "John D.",
  "email": "newemail@example.com"
}

---

Organization Endpoints

GET /api/organizations

List user's organizations.

Response:

{
  "organizations": [
    {
      "id": "uuid",
      "name": "My Team",
      "slug": "my-team",
      "role": "owner",
      "memberCount": 5,
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ]
}

POST /api/organizations

Create a new organization.

Request Body:

{
  "name": "My New Team",
  "slug": "my-new-team"
}

GET /api/organizations/{orgId}

Get organization details.

PATCH /api/organizations/{orgId}

Update organization.

DELETE /api/organizations/{orgId}

Delete organization (owner only).

GET /api/organizations/{orgId}/members

List organization members.

Response:

{
  "members": [
    {
      "id": "uuid",
      "userId": "user-uuid",
      "username": "johndoe",
      "displayName": "John Doe",
      "role": "owner",
      "joinedAt": "2026-01-01T00:00:00Z"
    }
  ]
}

POST /api/organizations/{orgId}/members

Add member to organization.

Request Body:

{
  "userId": "user-uuid",
  "role": "member"
}

PATCH /api/organizations/{orgId}/members/{memberId}

Update member role.

DELETE /api/organizations/{orgId}/members/{memberId}

Remove member from organization.

---

File Endpoints

GET /api/files

List files in a directory.

Query Parameters:

Parameter	Type	Description
path	string	Directory path (default: /)
orgId	string	Organization ID (optional)

Response:

{
  "files": [
    {
      "id": "uuid",
      "name": "document.pdf",
      "path": "/documents/document.pdf",
      "type": "file",
      "mimeType": "application/pdf",
      "size": 1048576,
      "createdAt": "2026-01-01T00:00:00Z",
      "modifiedAt": "2026-01-13T19:00:00Z"
    },
    {
      "id": "uuid",
      "name": "photos",
      "path": "/photos",
      "type": "folder",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ]
}

POST /api/files/upload

Upload a file.

Request: multipart/form-data

Field	Type	Description
file	file	The file to upload
path	string	Destination path
orgId	string	Organization ID (optional)

Response:

{
  "file": {
    "id": "uuid",
    "name": "uploaded-file.pdf",
    "path": "/documents/uploaded-file.pdf",
    "size": 1048576
  }
}

GET /api/files/download

Download a file.

Query Parameters:

Parameter	Type	Description
path	string	File path
orgId	string	Organization ID (optional)

Response: File binary with appropriate Content-Type header.

POST /api/files/folder

Create a folder.

Request Body:

{
  "path": "/new-folder",
  "orgId": "org-uuid"
}

DELETE /api/files

Delete a file or folder.

Query Parameters:

Parameter	Type	Description
path	string	Path to delete
orgId	string	Organization ID (optional)

POST /api/files/move

Move/rename a file or folder.

Request Body:

{
  "sourcePath": "/old-name.pdf",
  "destinationPath": "/new-name.pdf",
  "orgId": "org-uuid"
}

POST /api/files/copy

Copy a file or folder.

Request Body:

{
  "sourcePath": "/original.pdf",
  "destinationPath": "/copy.pdf",
  "orgId": "org-uuid"
}

---

Admin Endpoints

Requires admin or superadmin role.

GET /api/admin/users

List all users.

Query Parameters:

Parameter	Type	Description
page	int	Page number (default: 1)
limit	int	Items per page (default: 50)
search	string	Search by username/email

GET /api/admin/users/{userId}

Get user details.

PATCH /api/admin/users/{userId}

Update user (role, status).

DELETE /api/admin/users/{userId}

Delete user account.

Admin Invitations

GET /auth/admin/invitations

List admin invitations.

POST /auth/admin/invitations

Create admin invitation.

Request Body:

{
  "username": "newadmin",
  "roleId": "admin-role-uuid",
  "expiresIn": 86400
}

Response:

{
  "invitation": {
    "id": "uuid",
    "token": "invite-token",
    "expiresAt": "2026-01-14T19:00:00Z"
  }
}

POST /auth/admin/invitations/{token}/accept

Accept an admin invitation.

DELETE /auth/admin/invitations/{token}

Revoke an invitation.

---

Activity Endpoints

GET /api/activities

Get activity log.

Query Parameters:

Parameter	Type	Description
page	int	Page number
limit	int	Items per page
orgId	string	Filter by organization
userId	string	Filter by user
action	string	Filter by action type

Response:

{
  "activities": [
    {
      "id": "uuid",
      "userId": "user-uuid",
      "username": "johndoe",
      "action": "file.upload",
      "resourceType": "file",
      "resourceId": "/documents/report.pdf",
      "metadata": {
        "size": 1048576
      },
      "createdAt": "2026-01-13T19:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150
  }
}

---

Error Responses

All errors follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

Common Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing or invalid token
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Invalid request data
CONFLICT	409	Resource already exists
INTERNAL_ERROR	500	Server error

---

Rate Limiting

• Authentication endpoints: 10 requests/minute
• API endpoints: 100 requests/minute
• File uploads: 50 requests/hour

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705172400

---

Webhooks (Future)

Planned webhook events:

• user.created
• user.deleted
• file.uploaded
• file.deleted
• org.member.added
• org.member.removed