# 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
```json
{
  "error": "Error message description"
}
```

### Success Message Response
```json
{
  "message": "Success message description"
}
```

## Endpoints

### Authentication

#### Login
- **POST** `/auth/login`
- **Description**: Authenticate user and get access token
- **Request**:
  ```json
  {
    "email": "user@example.com",
    "password": "userpassword"
  }
  ```
- **Response** (200 OK):
  ```json
  {
    "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):
  ```json
  {
    "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**:
  ```json
  {
    "name": "Updated Name",
    "phone_number": "1234567890"
  }
  ```
- **Response** (200 OK):
  ```json
  {
    "user": {
      "id": "uuid",
      "name": "Updated Name",
      "phone_number": "1234567890"
    }
  }
  ```

### Workspace Management

#### Create Workspace
- **POST** `/workspaces`
- **Auth Required**: Yes
- **Request**:
  ```json
  {
    "name": "New Workspace"
  }
  ```
- **Response** (201 Created):
  ```json
  {
    "id": "uuid",
    "name": "New Workspace"
  }
  ```

#### Initialize Workspace Owner
- **POST** `/workspaces/owners/init`
- **Request**:
  ```json
  {
    "email": "owner@example.com",
    "name": "Owner Name",
    "phone_number": "1234567890"
  }
  ```
- **Response** (201 Created):
  ```json
  {
    "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**:
  ```json
  {
    "workspace_id": "uuid",
    "role": "member"
  }
  ```
- **Response** (200 OK):
  ```json
  {
    "message": "User added to workspace successfully"
  }
  ```

### Profile Management

#### List Profiles
- **GET** `/profiles`
- **Auth Required**: Yes
- **Response** (200 OK):
  ```json
  {
    "profiles": [
      {
        "id": "uuid",
        "name": "Profile Name",
        "workspace_id": "uuid"
      }
    ]
  }
  ```

#### Create Profile
- **POST** `/profiles`
- **Auth Required**: Yes
- **Request**:
  ```json
  {
    "name": "New Profile",
    "workspace_id": "uuid"
  }
  ```
- **Response** (201 Created):
  ```json
  {
    "profile": {
      "id": "uuid",
      "name": "New Profile",
      "workspace_id": "uuid"
    }
  }
  ```

#### Get Profile
- **GET** `/profiles/:id`
- **Auth Required**: Yes
- **Response** (200 OK):
  ```json
  {
    "profile": {
      "id": "uuid",
      "name": "Profile Name",
      "workspace_id": "uuid"
    }
  }
  ```

#### Update Profile
- **PUT** `/profiles/:id`
- **Auth Required**: Yes
- **Request**:
  ```json
  {
    "name": "Updated Profile Name"
  }
  ```
- **Response** (200 OK):
  ```json
  {
    "profile": {
      "id": "uuid",
      "name": "Updated Profile Name",
      "workspace_id": "uuid"
    }
  }
  ```

### Invitation Management

#### Create Invitation
- **POST** `/invitations`
- **Auth Required**: Yes
- **Request**:
  ```json
  {
    "email": "newuser@example.com",
    "workspace_id": "uuid",
    "role": "member"
  }
  ```
- **Response** (201 Created):
  ```json
  {
    "id": "uuid",
    "email": "newuser@example.com",
    "status": "pending",
    "expires_at": "2024-03-21T12:00:00Z",
    "workspace_id": "uuid"
  }
  ```

#### Accept Invitation
- **POST** `/invitations/accept`
- **Request**:
  ```json
  {
    "email": "newuser@example.com",
    "name": "New User",
    "phone_number": "1234567890",
    "password": "userpassword",
    "token": "invitation-token"
  }
  ```
- **Response** (201 Created):
  ```json
  {
    "user": {
      "id": "uuid",
      "email": "newuser@example.com",
      "name": "New User"
    },
    "workspace_id": "uuid"
  }
  ```

#### Validate Invitation
- **GET** `/invitations/validate?token=<token>`
- **Response** (200 OK):
  ```json
  {
    "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