byom-customer-api/docs/api.md

BYOM Core API Documentation

Overview

This document describes the BYOM Core API endpoints, including request/response formats and authentication requirements.

Base URL

All API endpoints are prefixed with: /api/v1/core

Authentication

Most endpoints require authentication using a JWT token. Include the token in the Authorization header:

Authorization: Bearer <token>

Common Response Types

Error Response

{
  "error": "Error message description"
}

Success Message Response

{
  "message": "Success message description"
}

Endpoints

Authentication

Login

• POST /auth/login
• Description: Authenticate user and get access token

• Request:

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

• Response (200 OK):

  {
  "token": "jwt.token.here",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "User Name",
    "role": "user"
  }
  }
  

User Management

Get Current User

• GET /users/current
• Auth Required: Yes

• Response (200 OK):

  {
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "User Name",
    "phone_number": "1234567890",
    "role": "user",
    "status": "active"
  },
  "workspaces": [
    {
      "id": "uuid",
      "name": "Workspace Name"
    }
  ]
  }
  

Update Current User

• PUT /users/current
• Auth Required: Yes

• Request:

  {
  "name": "Updated Name",
  "phone_number": "1234567890"
  }
  

• Response (200 OK):

  {
  "user": {
    "id": "uuid",
    "name": "Updated Name",
    "phone_number": "1234567890"
  }
  }
  

Workspace Management

Create Workspace

• POST /workspaces
• Auth Required: Yes

• Request:

  {
  "name": "New Workspace"
  }
  

• Response (201 Created):

  {
  "id": "uuid",
  "name": "New Workspace"
  }
  

Initialize Workspace Owner

• POST /workspaces/owners/init

• Request:

  {
  "email": "owner@example.com",
  "name": "Owner Name",
  "phone_number": "1234567890"
  }
  

• Response (201 Created):

  {
  "user": {
    "id": "uuid",
    "email": "owner@example.com",
    "name": "Owner Name",
    "role": "owner",
    "status": "pending"
  }
  }
  

Add Workspace Member

• POST /workspaces/:id/members
• Auth Required: Yes

• Request:

  {
  "workspace_id": "uuid",
  "role": "member"
  }
  

• Response (200 OK):

  {
  "message": "User added to workspace successfully"
  }
  

Profile Management

List Profiles

• GET /profiles
• Auth Required: Yes

• Response (200 OK):

  {
  "profiles": [
    {
      "id": "uuid",
      "name": "Profile Name",
      "workspace_id": "uuid"
    }
  ]
  }
  

Create Profile

• POST /profiles
• Auth Required: Yes

• Request:

  {
  "name": "New Profile",
  "workspace_id": "uuid"
  }
  

• Response (201 Created):

  {
  "profile": {
    "id": "uuid",
    "name": "New Profile",
    "workspace_id": "uuid"
  }
  }
  

Get Profile

• GET /profiles/:id
• Auth Required: Yes

• Response (200 OK):

  {
  "profile": {
    "id": "uuid",
    "name": "Profile Name",
    "workspace_id": "uuid"
  }
  }
  

Update Profile

• PUT /profiles/:id
• Auth Required: Yes

• Request:

  {
  "name": "Updated Profile Name"
  }
  

• Response (200 OK):

  {
  "profile": {
    "id": "uuid",
    "name": "Updated Profile Name",
    "workspace_id": "uuid"
  }
  }
  

Invitation Management

Create Invitation

• POST /invitations
• Auth Required: Yes

• Request:

  {
  "email": "newuser@example.com",
  "workspace_id": "uuid",
  "role": "member"
  }
  

• Response (201 Created):

  {
  "id": "uuid",
  "email": "newuser@example.com",
  "status": "pending",
  "expires_at": "2024-03-21T12:00:00Z",
  "workspace_id": "uuid"
  }
  

Accept Invitation

• POST /invitations/accept

• Request:

  {
  "email": "newuser@example.com",
  "name": "New User",
  "phone_number": "1234567890",
  "password": "userpassword",
  "token": "invitation-token"
  }
  

• Response (201 Created):

  {
  "user": {
    "id": "uuid",
    "email": "newuser@example.com",
    "name": "New User"
  },
  "workspace_id": "uuid"
  }
  

Validate Invitation

• GET /invitations/validate?token=<token>

• Response (200 OK):

  {
  "valid": true,
  "workspace_id": "uuid",
  "email": "newuser@example.com"
  }
  

HTTP Status Codes

• 200 OK: Successful request
• 201 Created: Resource created successfully
• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Authentication required or failed
• 403 Forbidden: Permission denied
• 404 Not Found: Resource not found
• 500 Internal Server Error: Server error

Data Types

User Roles

• owner: Workspace owner
• admin: Workspace administrator
• member: Regular workspace member

Invitation Status

• pending: Invitation awaiting acceptance
• accepted: Invitation has been accepted
• expired: Invitation has expired
• cancelled: Invitation was cancelled