← Back to Documentation

BDM Universal API

Complete API Reference & Integration Guide

Quick Navigation

Introduction

The BDM Universal API provides a standardized interface for all BDM modules. This framework enables:

  • User-to-User Sharing: Share module access with team members
  • Guest Access: Secure external access for customers, vendors, employees
  • Multiple Authentication: Sanctum tokens, API keys, guest tokens
  • Rate Limiting: Configurable limits per user/token
  • Webhooks: Real-time event notifications
  • Export/Import: Standardized data exchange

Base URL

https://bdmhub.com/api/v1

Authentication

1. Bearer Token (Sanctum)

For authenticated users. Include in Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Login

POST /api/login

Authenticate and receive access token

Request Body:

{
  "email": "user@example.com",
  "password": "secret123"
}

Response (200 OK):

{
  "success": true,
  "message": "Logged in successfully",
  "data": {
    "token": "1|abc123def456...",
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "user@example.com"
    }
  }
}

Logout

POST /api/logout

Revoke current access token

2. API Token

For service-to-service communication. Prefix token with bdm_

Authorization: Bearer bdm_YOUR_API_TOKEN_HERE

3. Guest Token

For external access. No Authorization header needed - token is in URL:

GET /api/guest/resource/{TOKEN}

Permission Management

Share module access with other users with role-based permissions.

GET /api/permissions

List all permissions for authenticated user

Query Parameters:

  • page - Page number (default: 1)
  • per_page - Items per page (default: 15)
  • module_slug - Filter by module

Response (200 OK):

{
  "success": true,
  "data": [
    {
      "id": 1,
      "owner_user_id": 5,
      "shared_with_user_id": 10,
      "module_slug": "accounting",
      "role": "manager",
      "status": "active",
      "expires_at": "2026-10-27T00:00:00.000000Z",
      "created_at": "2025-10-27T10:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 1,
    "per_page": 15
  }
}
POST /api/permissions

Share module access with another user

Request Body:

{
  "email": "colleague@example.com",
  "module_slug": "accounting",
  "role": "manager",
  "expires_at": "2026-12-31"
}

Available Roles:

  • owner - Full access (cannot be assigned)
  • admin - Nearly full access, cannot manage permissions
  • manager - Daily operations, approvals, reporting
  • staff - Operational tasks, limited editing
  • viewer - Read-only access
PATCH /api/permissions/{id}/role

Change user's role

{
  "role": "admin"
}
DELETE /api/permissions/{id}

Revoke user's access to module

Guest Access

Provide secure, limited access to specific resources for external users.

Use Cases

  • • Customers viewing invoices and making payments
  • • Vendors accessing purchase orders
  • • Employees viewing payslips
  • • Partners viewing shared reports
GET /api/guest/access/{token}

Validate token and get security requirements

Response (200 OK):

{
  "success": true,
  "data": {
    "valid": true,
    "requires_password": true,
    "requires_verification": false,
    "resource_type": "accounting_invoice",
    "guest_email": "customer@example.com",
    "permissions": ["view", "download", "pay"],
    "view_limit": 10,
    "views_remaining": 8
  }
}
POST /api/guest/authenticate/{token}

Submit password and/or verification code

{
  "password": "secret123",
  "verification_code": "123456"
}
GET /api/guest/resource/{token}

Access the resource

Response (200 OK):

{
  "success": true,
  "data": {
    "invoice": {
      "number": "INV-2025-001",
      "customer_name": "Acme Corp",
      "total": 1500.00,
      "status": "unpaid",
      "due_date": "2025-11-27"
    }
  }
}

API Tokens

Create and manage API tokens for service-to-service authentication.

GET /api/tokens

List all API tokens for authenticated user

POST /api/tokens

Create new API token

Request Body:

{
  "name": "Production API",
  "scopes": ["accounting.*", "stock_control.view"],
  "rate_limit_per_minute": 200,
  "expires_at": "2026-12-31"
}

Scope Patterns:

  • *.* - Full access to all modules
  • accounting.* - Full access to accounting module
  • *.view - View access to all modules
  • accounting.invoices.view - Specific resource action

Response (201 Created):

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Production API",
    "token": "bdm_abc123def456...",
    "scopes": ["accounting.*", "stock_control.view"]
  }
}

⚠️ Important: Store the token securely. It won't be shown again!

DELETE /api/tokens/{id}

Revoke API token

Accounting Module

GET /api/v1/accounting/invoices

List invoices with pagination and filters

Query Parameters:

  • page - Page number
  • per_page - Items per page
  • search - Full-text search
  • filter[status] - Filter by status (paid, unpaid, overdue)
  • sort_by - Sort field
  • sort_order - asc or desc

Example Request:

GET /api/v1/accounting/invoices?filter[status]=unpaid&sort_by=due_date
POST /api/v1/accounting/invoices

Create new invoice

{
  "customer_name": "Acme Corp",
  "customer_email": "billing@acme.com",
  "items": [
    {
      "description": "Web Development",
      "quantity": 40,
      "unit_price": 100.00
    }
  ],
  "notes": "Payment terms: Net 30"
}

Rate Limits

Auth Type Per Minute Per Hour
Authenticated User 100 5,000
API Token Configurable Configurable
Guest Access 20 100
Anonymous 10 50

Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1698765432

Error Handling

Standard Error Format

{
  "success": false,
  "message": "Error description",
  "errors": {
    "field": ["Error message"]
  },
  "meta": {
    "timestamp": "2025-10-27T10:30:00Z"
  }
}

HTTP Status Codes

Code Meaning
200 Success - GET, PUT, PATCH
201 Created - POST
204 No Content - DELETE
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
422 Validation Error
429 Rate Limit Exceeded
500 Internal Server Error